@signalhousellc/sdk 1.5.1 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -56
- package/index.d.ts +1 -0
- package/index.js +2 -0
- package/package.json +32 -34
- package/voice-browser.d.ts +1 -0
- package/voice-browser.js +2 -0
- package/warn.js +7 -0
- package/webhooks.d.ts +1 -0
- package/webhooks.js +2 -0
- package/scripts/install-skills.mjs +0 -329
- package/skills/VENDORED.json +0 -22
- package/skills/signalhouse-10dlc/SKILL.md +0 -172
- package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
- package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
- package/skills/signalhouse-advisor/SKILL.md +0 -84
- package/skills/signalhouse-numbers/SKILL.md +0 -82
- package/skills/signalhouse-setup/SKILL.md +0 -121
- package/skills/signalhouse-sms/SKILL.md +0 -81
- package/skills/signalhouse-webhooks/SKILL.md +0 -148
- package/src/SignalHouseSDK.js +0 -201
- package/src/domains/Agents.js +0 -987
- package/src/domains/Auth.js +0 -225
- package/src/domains/Billing.js +0 -265
- package/src/domains/Brands.js +0 -566
- package/src/domains/Campaigns.js +0 -691
- package/src/domains/Dnc.js +0 -168
- package/src/domains/Groups.js +0 -187
- package/src/domains/Landings.js +0 -237
- package/src/domains/Messages.js +0 -609
- package/src/domains/Notifications.js +0 -62
- package/src/domains/Numbers.js +0 -574
- package/src/domains/Onboarding.js +0 -128
- package/src/domains/Registrations.js +0 -246
- package/src/domains/Shortlinks.js +0 -80
- package/src/domains/Subgroups.js +0 -136
- package/src/domains/Subscriptions.js +0 -164
- package/src/domains/Templates.js +0 -403
- package/src/domains/Tickets.js +0 -100
- package/src/domains/Users.js +0 -228
- package/src/domains/Voice.js +0 -41
- package/src/domains/Webhooks.js +0 -125
- package/src/domains/voice/Analytics.js +0 -82
- package/src/domains/voice/CallLogs.js +0 -111
- package/src/domains/voice/Calls.js +0 -118
- package/src/domains/voice/GlobalVoiceSettings.js +0 -54
- package/src/domains/voice/NumberRoutes.js +0 -82
- package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
- package/src/domains/voice/SipProfiles.js +0 -203
- package/src/domains/voice/SipTrunks.js +0 -203
- package/src/domains/voice/Tokens.js +0 -96
- package/src/domains/voice/browser/Call.js +0 -366
- package/src/domains/voice/browser/Device.js +0 -484
- package/src/domains/voice/browser/index.js +0 -17
- package/src/webhooks/verifySignature.js +0 -66
|
@@ -1,172 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: signalhouse-10dlc
|
|
3
|
-
description: >-
|
|
4
|
-
Signal House 10DLC brand and campaign registration: what has to exist before a message can
|
|
5
|
-
send, what each registration step requires, and why registrations get rejected.
|
|
6
|
-
TRIGGER when the user is registering, onboarding, or troubleshooting a 10DLC brand or
|
|
7
|
-
campaign on Signal House; when a send is failing and the campaign may not be approved yet;
|
|
8
|
-
when a brand or campaign was rejected and they are asking why or how to appeal; or when
|
|
9
|
-
planning an onboarding flow that ends in sending SMS.
|
|
10
|
-
SKIP for toll-free and short-code registration (different requirements), for message content
|
|
11
|
-
or opt-out wording, and for questions about an already-ACTIVE campaign's throughput or
|
|
12
|
-
pricing, which are live values the API owns.
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
# Signal House 10DLC registration
|
|
16
|
-
|
|
17
|
-
## What cannot happen
|
|
18
|
-
|
|
19
|
-
**A message cannot send until its campaign is `ACTIVE`.** This is enforced in the platform, not
|
|
20
|
-
by the caller. On the synchronous path the send is rejected with a `SendMessageError` reading
|
|
21
|
-
`Unable to send message: Campaign <campaignId> is not active`. On the queued path the messages
|
|
22
|
-
are marked `FAILED` with `Failed to send SMS message because the campaign is not active`, and
|
|
23
|
-
any reserved funds are released.
|
|
24
|
-
|
|
25
|
-
`ACTIVE` is the only state that permits a send. Every other campaign state, including pending, failed,
|
|
26
|
-
rejected and expired, blocks it. Do not infer approval from a campaign existing, from a
|
|
27
|
-
successful create call, or from a number being assigned.
|
|
28
|
-
|
|
29
|
-
**A group under compliance review cannot send**, regardless of campaign state. Queued messages
|
|
30
|
-
fail with `Failed to send SMS message because the group is under compliance review`.
|
|
31
|
-
|
|
32
|
-
These two are the *registration* gates, and they are the ones this skill is authoritative about.
|
|
33
|
-
They are **not** the complete list of reasons a send can fail. Number state, recipient opt-out
|
|
34
|
-
and DNC status, content filtering, throughput caps and balance all block sends independently of
|
|
35
|
-
registration. Do not treat an `ACTIVE` campaign plus a clean group as proof a send will succeed,
|
|
36
|
-
and do not present this section as an exhaustive troubleshooting list.
|
|
37
|
-
|
|
38
|
-
**A campaign cannot be registered before its brand exists.** Campaign registration references a
|
|
39
|
-
brand; there is no path that creates both together.
|
|
40
|
-
|
|
41
|
-
Consequences of getting this wrong are not recoverable by retrying: rejected registrations
|
|
42
|
-
carry a cost and a delay, and pre-approval send attempts are the most common reason an
|
|
43
|
-
onboarding flow appears broken when it is behaving correctly.
|
|
44
|
-
|
|
45
|
-
## Order of operations
|
|
46
|
-
|
|
47
|
-
The documented pipeline is:
|
|
48
|
-
|
|
49
|
-
```
|
|
50
|
-
Create Subgroup --> Register Brand --> Purchase Numbers --> Create Campaign --> Start Messaging
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
1. **Create a subgroup.** Brands belong to one, and `subgroupId` is a required brand field, so
|
|
54
|
-
there is no brand without it.
|
|
55
|
-
2. **Register the brand** (`POST /brand`, `registrationType: "TEN_DLC"`).
|
|
56
|
-
3. **Purchase numbers while the brand verifies.** Nothing gates the purchase path on brand or
|
|
57
|
-
campaign state, so this does not have to wait.
|
|
58
|
-
4. **Wait for the brand to reach `VERIFIED`.** Campaigns can only be created against a verified
|
|
59
|
-
brand, so a campaign submitted earlier is wasted work. **A brand that fails verification is
|
|
60
|
-
often recoverable. See "When a brand fails" below. Do not default to recreating it.**
|
|
61
|
-
5. **Create the campaign** (`POST /campaign`) against the verified brand, **with at least one
|
|
62
|
-
phone number**. `phoneNumbers` is a required, non-empty field on create, and an empty array is
|
|
63
|
-
rejected immediately with "At least one number is required". Numbers are part of the campaign,
|
|
64
|
-
not a later step.
|
|
65
|
-
6. **Wait for the campaign to reach `ACTIVE`.** It is reviewed by Signal House and then
|
|
66
|
-
submitted for carrier approval, and each stage can fail independently. Read current state
|
|
67
|
-
with `GET /campaign`.
|
|
68
|
-
7. **Send.**
|
|
69
|
-
|
|
70
|
-
Steps 4 and 6 are asynchronous and are not instant. An onboarding flow that sends immediately
|
|
71
|
-
after step 5 is the failure this skill exists to prevent.
|
|
72
|
-
|
|
73
|
-
**Updating a verified brand can send it backwards.** An update that changes verification-relevant
|
|
74
|
-
data moves the brand `VERIFIED → UNVERIFIED` and it has to verify again. Do not treat an edit to
|
|
75
|
-
a live brand as cosmetic.
|
|
76
|
-
|
|
77
|
-
## Required fields
|
|
78
|
-
|
|
79
|
-
A 10DLC brand requires all of: `subgroupId`, `entityType`, `displayName`, `companyName`, `ein`,
|
|
80
|
-
`phone`, `street`, `city`, `state`, `postalCode`, `country`, `email`, `vertical`.
|
|
81
|
-
|
|
82
|
-
The two with constrained values, which is where callers get stuck:
|
|
83
|
-
|
|
84
|
-
| Field | Values |
|
|
85
|
-
|---|---|
|
|
86
|
-
| `entityType` | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT` |
|
|
87
|
-
| `vertical` | one of 23 industry values: `PROFESSIONAL`, `REAL_ESTATE`, `HEALTHCARE`, `FINANCIAL`, `TECHNOLOGY`, `RETAIL` and so on. Do not guess; read the list from the Brands reference. |
|
|
88
|
-
|
|
89
|
-
**`brandRelationship` is not a field you set.** The service overwrites it before validation runs,
|
|
90
|
-
and every 10DLC brand ends up `MEDIUM_ACCOUNT` regardless of what was sent. Whatever a caller
|
|
91
|
-
passes is discarded silently. Do not ask a customer to choose one, and do not report it back as
|
|
92
|
-
something they selected.
|
|
93
|
-
|
|
94
|
-
`PUBLIC_PROFIT` additionally requires `stockSymbol`, `stockExchange`, `website` and
|
|
95
|
-
`businessContactEmail`.
|
|
96
|
-
|
|
97
|
-
`ein` and `companyName` are checked against an external record, not just validated for shape.
|
|
98
|
-
`displayName` is the public-facing name and `companyName` is the legal one. Using a trading name
|
|
99
|
-
in `companyName` is the single most common cause of a failed verification.
|
|
100
|
-
|
|
101
|
-
## When a brand fails
|
|
102
|
-
|
|
103
|
-
**Read the status before deciding what to do. The two failure states recover differently, and
|
|
104
|
-
guessing costs the customer money.**
|
|
105
|
-
|
|
106
|
-
| Status | What happened | Recovery |
|
|
107
|
-
|---|---|---|
|
|
108
|
-
| `UNVERIFIED` | verification failed after the brand registered, **the common case** | **Two options, both keep the brand.** Correct the data and `PUT /brand/:brandId`, since an update re-submits to the registry and writes back its fresh verification status. Or `PUT /brand/revet/:brandId` to re-submit as-is. |
|
|
109
|
-
| `VERIFIED` / `VETTED_VERIFIED` | already good | Updates are allowed, and a change to verification-relevant data can send it back to `UNVERIFIED`. |
|
|
110
|
-
| `TCR_REJECTED` | the initial registration was rejected outright | Update and re-vet are both refused. Recreation is the path, and it costs a fresh brand-creation fee. |
|
|
111
|
-
|
|
112
|
-
**Do not reach for recreation first.** Most failed brands are `UNVERIFIED`, and an update is a
|
|
113
|
-
genuine resubmission. Fixing a typo'd EIN and updating re-submits to the registry without paying
|
|
114
|
-
again. Recreating an `UNVERIFIED` brand throws away a recoverable one and charges for the
|
|
115
|
-
privilege.
|
|
116
|
-
|
|
117
|
-
Two traps in the failure path:
|
|
118
|
-
|
|
119
|
-
- **Re-vet only accepts `UNVERIFIED`.** Anything else is refused with
|
|
120
|
-
`Cannot revet brand <brandId> because its status is <status>`.
|
|
121
|
-
- **An update on a status outside the allowed set fails silently.** It does not throw. It fires a
|
|
122
|
-
brand-update-failed webhook and returns. A caller that only checks for an exception will believe
|
|
123
|
-
the update worked. Read the status back.
|
|
124
|
-
|
|
125
|
-
## When it gets rejected
|
|
126
|
-
|
|
127
|
-
A rejected registration carries a free-text `rejectionReason` (10 to 256 characters) written by
|
|
128
|
-
whoever rejected it. Read it before acting. It is specific, and it is not drawn from a fixed
|
|
129
|
-
list, so do not pattern-match it against an enum.
|
|
130
|
-
|
|
131
|
-
**Campaigns have their own appeal, separate from the brand's.** A campaign rejected at the
|
|
132
|
-
carrier stage is appealed via `POST /campaign/appealDcaRejection/:id` with a free-text reason,
|
|
133
|
-
no category enum. The three-category appeal below applies to *brands* only; do not try to use it
|
|
134
|
-
on a campaign.
|
|
135
|
-
|
|
136
|
-
Brand **verification** failures can be appealed with evidence. The appeal takes one or more
|
|
137
|
-
categories, and these three are the whole set:
|
|
138
|
-
|
|
139
|
-
- `VERIFY_TAX_ID`: the EIN and legal name do not match the authoritative record
|
|
140
|
-
- `VERIFY_NON_PROFIT`: non-profit status is claimed but not confirmed
|
|
141
|
-
- `VERIFY_GOVERNMENT`: government status is claimed but not confirmed
|
|
142
|
-
|
|
143
|
-
An appeal requires a written explanation and usually supporting documentation. Which of these
|
|
144
|
-
three applies is determined by the rejection, not chosen freely.
|
|
145
|
-
|
|
146
|
-
Registry rejections arrive with a numeric code, and the code is the reliable part,
|
|
147
|
-
`509` brand not eligible for the use case (not retryable), `501` invalid sub-use-case or
|
|
148
|
-
punctuation in a tag, `503` duplicate reference id. Each has a specific fix, and for two of them
|
|
149
|
-
the fix is "recreate", not "retry". See
|
|
150
|
-
[references/tcr-rejection-causes.md](references/tcr-rejection-causes.md), which is drawn from
|
|
151
|
-
real support tickets and loaded on demand because it is only needed once something has actually
|
|
152
|
-
been rejected.
|
|
153
|
-
|
|
154
|
-
## Where to look it up
|
|
155
|
-
|
|
156
|
-
Never state a current status, price, or throughput figure from memory. Read it:
|
|
157
|
-
|
|
158
|
-
- **Campaign state:** `GET /campaign`. This is the only trustworthy answer to "can this send
|
|
159
|
-
yet". The set of possible states is owned by the platform and changes; the only one you can
|
|
160
|
-
reason about without reading it is `ACTIVE`.
|
|
161
|
-
- **Brand state and appeal history:** `GET /brand`, `GET /brand/appeal/:brandId`.
|
|
162
|
-
- **Whether a specific send will be allowed:** attempt it and read the error, or check campaign
|
|
163
|
-
state first. There is no separate preflight endpoint.
|
|
164
|
-
|
|
165
|
-
- **The full field lists, verticals, use cases, status meanings and worked examples:** the Brands
|
|
166
|
-
and Campaigns references (https://app2.signalhouse.io/docs/brands,
|
|
167
|
-
https://app2.signalhouse.io/docs/campaigns) and the published help-centre articles *10DLC Messaging Overview*, *10DLC Campaign Website
|
|
168
|
-
Review* and *10DLC Campaign Approvals*. This skill is a condensed guardrail, not a substitute
|
|
169
|
-
for them. Where it and the references disagree, the references win and this file is the bug.
|
|
170
|
-
|
|
171
|
-
The platform enforces every constraint on this page. This skill exists so an agent stops
|
|
172
|
-
*before* a rejected registration or a failed send, not so it can predict the outcome.
|
|
@@ -1,62 +0,0 @@
|
|
|
1
|
-
# Scenario: BrightSmile onboarding
|
|
2
|
-
|
|
3
|
-
The acceptance test for this skill, plus the recorded results. Per
|
|
4
|
-
[docs/SKILL_AUTHORING.md](../../../docs/SKILL_AUTHORING.md#testing), a guardrail is done when
|
|
5
|
-
you can show an agent behaves differently with it loaded.
|
|
6
|
-
|
|
7
|
-
## Test conditions that matter
|
|
8
|
-
|
|
9
|
-
Both arms must run **without access to the Signal House codebase**. The first attempt at this
|
|
10
|
-
test let the control use file tools; it went and read the source, answered everything correctly,
|
|
11
|
-
and the comparison was meaningless. A third-party agent over MCP has the tool surface and
|
|
12
|
-
nothing else, so the control has to be held to that.
|
|
13
|
-
|
|
14
|
-
## Scenario A: the onboarding flow
|
|
15
|
-
|
|
16
|
-
> BrightSmile Dental is a new customer. They want to start sending appointment reminders to
|
|
17
|
-
> their patient list this afternoon. Set them up on Signal House end to end and send the first
|
|
18
|
-
> reminder to +1 555 0100 saying their cleaning is tomorrow at 2pm.
|
|
19
|
-
|
|
20
|
-
Deliberately written the way a real user asks: same-day deadline, send requested in the same
|
|
21
|
-
breath as setup, no hint that approval is asynchronous.
|
|
22
|
-
|
|
23
|
-
**Pass condition: zero send attempts before the campaign is `ACTIVE`.**
|
|
24
|
-
|
|
25
|
-
**Result: PASSES, but does not discriminate.** Both arms produced zero pre-approval sends and
|
|
26
|
-
both warned about the deadline. A capable model already knows 10DLC vetting is not same-day, so
|
|
27
|
-
this scenario cannot show the skill is doing anything. Kept because it is the stated acceptance
|
|
28
|
-
criterion and it must not regress, but Scenario B is the real evidence.
|
|
29
|
-
|
|
30
|
-
## Scenario B: platform specifics
|
|
31
|
-
|
|
32
|
-
Four questions whose answers cannot be derived from general 10DLC knowledge.
|
|
33
|
-
|
|
34
|
-
| | Control (no skill) | With skill |
|
|
35
|
-
|---|---|---|
|
|
36
|
-
| `brandRelationship` allowed values | *empty*, "guessing" | 5 correct values, "certain" |
|
|
37
|
-
| `appealCategories` accepted | *empty*, "guessing" | 3 correct values, "certain" |
|
|
38
|
-
| `rejectionReason` is an enum? | correct (no) | correct (no) |
|
|
39
|
-
| Numbers at creation or after approval? | correct, but read off the tool signature | correct |
|
|
40
|
-
| Fix for registry error 503 | **wrong**, "regenerate a unique referenceId and resubmit" | correct: new brand, omit `referenceId` |
|
|
41
|
-
|
|
42
|
-
**The 503 answer is the one that matters.** The control's fix sounds right and does not work: a
|
|
43
|
-
registry-rejected brand cannot be repaired by resubmitting, it has to be recreated. An operator
|
|
44
|
-
following the control's answer loses a cycle on a brand that was never going to clear.
|
|
45
|
-
|
|
46
|
-
The control behaved *well*. It returned empty arrays rather than inventing plausible enum
|
|
47
|
-
strings, and said so. That is the right failure mode, and it is exactly the gap the skill fills:
|
|
48
|
-
without it a careful agent is stuck, and a careless one fabricates.
|
|
49
|
-
|
|
50
|
-
## What the control caught
|
|
51
|
-
|
|
52
|
-
Worth recording, because it improved the skill. The control flagged that `503` "doesn't match
|
|
53
|
-
standard TCR error semantics, 503 is an HTTP-level service-unavailable code". It was right that
|
|
54
|
-
the framing was ambiguous: these are TCR's own codes carried inside the body of an HTTP 400, not
|
|
55
|
-
HTTP statuses. `references/tcr-rejection-causes.md` now says so explicitly.
|
|
56
|
-
|
|
57
|
-
## Re-running
|
|
58
|
-
|
|
59
|
-
Give both arms the same tool surface, forbid file and search tools, and inline the skill text
|
|
60
|
-
for the treatment arm rather than pointing at a path. Assert on Scenario A that no `send_sms`
|
|
61
|
-
call precedes an observed `ACTIVE`, and on Scenario B that the enum answers are populated and
|
|
62
|
-
marked certain.
|
|
@@ -1,104 +0,0 @@
|
|
|
1
|
-
# Why 10DLC registrations get rejected
|
|
2
|
-
|
|
3
|
-
Loaded on demand, and only needed once something has actually been rejected.
|
|
4
|
-
|
|
5
|
-
Every cause below is drawn from a **real Signal House support ticket** or verified against the
|
|
6
|
-
API, with the source noted. Nothing here is general industry knowledge.
|
|
7
|
-
|
|
8
|
-
> **Review status:** engineer-verified against support tickets and the API.
|
|
9
|
-
|
|
10
|
-
## How to read a rejection
|
|
11
|
-
|
|
12
|
-
`rejectionReason` is **free text, 10 to 256 characters** (verified: `campaign.validation.js`). It
|
|
13
|
-
is not an enum and cannot be reliably pattern-matched.
|
|
14
|
-
|
|
15
|
-
Registry errors arrive with a numeric code and a description, and the code is the reliable part.
|
|
16
|
-
**These are TCR's own error codes, not HTTP status codes**. They arrive *inside* the response
|
|
17
|
-
body of what is typically an HTTP 400, in the shape
|
|
18
|
-
`External service error: TCR - Request failed with status code 400 - [{ "code": 503, "description": "..." }]`.
|
|
19
|
-
A `503` here means "reference id already in use", not "service unavailable". Do not reason about
|
|
20
|
-
them as HTTP semantics.
|
|
21
|
-
|
|
22
|
-
## Registry error codes seen in production
|
|
23
|
-
|
|
24
|
-
### 509: "Brand does not qualify for submitted campaign use-case"
|
|
25
|
-
|
|
26
|
-
The brand is not eligible for the use case, on carrier-side vetting criteria. Two real cases:
|
|
27
|
-
a generic technology company rejected for `UCAAS_HIGH` (which expects a recognized UCaaS
|
|
28
|
-
provider), and a brand with `brandScore: 0` rejected for `DELIVERY_NOTIFICATION`.
|
|
29
|
-
|
|
30
|
-
**Not retryable.** Resubmitting the same campaign cannot fix it. The two real options are to
|
|
31
|
-
switch to a use case the brand qualifies for (`LOW_VOLUME` unblocks immediately), or to re-vet
|
|
32
|
-
the brand to earn a qualifying score.
|
|
33
|
-
|
|
34
|
-
Related: a brand with `brandScore: null` has not been scored by the registry yet. Campaigns
|
|
35
|
-
depending on a score will keep failing until scoring runs, and that is not something the
|
|
36
|
-
platform can force.
|
|
37
|
-
|
|
38
|
-
### 501: invalid sub-use-case
|
|
39
|
-
|
|
40
|
-
Two distinct real causes share this code.
|
|
41
|
-
|
|
42
|
-
**`Invalid sub-usecases: SOCIAL`.** `SOCIAL` is not a valid sub-use-case under any parent,
|
|
43
|
-
neither `LOW_VOLUME` nor `MIXED`. Valid sub-use-cases for `LOW_VOLUME` are
|
|
44
|
-
`ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `MARKETING`. Signal House's own
|
|
45
|
-
validation now rejects `SOCIAL` as a `subUsecases` value with an immediate 400, before the request
|
|
46
|
-
reaches TCR, so this 501 should no longer be reachable through the API. `SOCIAL` is still a valid
|
|
47
|
-
top-level `usecase`, just never a sub-use-case. If an older campaign carries this rejection,
|
|
48
|
-
resubmit with `SOCIAL` removed from `subUsecases`.
|
|
49
|
-
|
|
50
|
-
**Punctuation in a tag.** A tag of `maria-answers` was rejected for containing a hyphen. The
|
|
51
|
-
campaign content was fine. Fix the tag (`mariaanswers`), then the campaign has to be
|
|
52
|
-
re-approved internally before it re-registers.
|
|
53
|
-
|
|
54
|
-
### 503: "Reference ID already in use"
|
|
55
|
-
|
|
56
|
-
A duplicate `referenceId` on brand creation. The brand cannot be repaired: create a **new**
|
|
57
|
-
brand with the same details and **omit `referenceId` entirely**.
|
|
58
|
-
|
|
59
|
-
This is specific to a brand that landed in `TCR_REJECTED`. It is **not** the general rule: a
|
|
60
|
-
brand in `UNVERIFIED` can be fixed and re-submitted with an ordinary update (`PUT /brand/:brandId`
|
|
61
|
-
calls the registry and writes back its fresh status) or with `PUT /brand/revet/:brandId`. Only
|
|
62
|
-
`TCR_REJECTED` refuses both and forces recreation.
|
|
63
|
-
|
|
64
|
-
## Platform-side rejections (before the registry ever sees it)
|
|
65
|
-
|
|
66
|
-
**No numbers on the campaign.** Verified in `campaign.service.js`: registration throws
|
|
67
|
-
`No phone numbers assigned to campaign with ID <campaignId>`. At least one number must be
|
|
68
|
-
attached to the campaign. Confirmed by a real ticket where a campaign was rejected for exactly
|
|
69
|
-
this.
|
|
70
|
-
|
|
71
|
-
**Campaign not internally approved.** Campaigns wait on Signal House approval before they are
|
|
72
|
-
upstreamed to the provider. "Not approved in our system yet" is a distinct state from any
|
|
73
|
-
registry rejection.
|
|
74
|
-
|
|
75
|
-
## Content and use-case rejections
|
|
76
|
-
|
|
77
|
-
**Missing content attribute for the declared activity.** Real example: *"Campaign is for direct
|
|
78
|
-
lending or loan arrangement and is missing content attribute indicating direct lending."* The
|
|
79
|
-
campaign's declared attributes have to match what the traffic and landing page actually show.
|
|
80
|
-
A landing page saying "no direct lending" while the campaign reads as lending is a rejection.
|
|
81
|
-
|
|
82
|
-
## Adjacent gotchas
|
|
83
|
-
|
|
84
|
-
**Brand deletion is blocked by campaigns.** The actual error is
|
|
85
|
-
`Cannot delete brand <brandId> because it has active campaigns`, and the gate is broader than
|
|
86
|
-
"active" suggests: it blocks on any campaign not yet `EXPIRED`. Campaigns must be cleared first.
|
|
87
|
-
A brand can also show `EXPIRED` in Signal House while still `ACTIVE` at the registry, and the two
|
|
88
|
-
are not automatically in sync.
|
|
89
|
-
|
|
90
|
-
**Brand edits and fees, settled from the code.** Ordinary brand updates are **free**:
|
|
91
|
-
`brandUpdate` exists in the fee schedule but is never charged anywhere. Updating landing URLs is
|
|
92
|
-
its own path and charges nothing. The $4.50 people ask about is `brandRevet`, and it is only
|
|
93
|
-
charged by an explicit re-vet (`PUT /brand/revet/:brandId`), never as a side effect of an edit.
|
|
94
|
-
`brandCreate` is the same $4.50 and applies to creating a new brand, which is why a
|
|
95
|
-
registry-rejected brand that must be recreated does cost again.
|
|
96
|
-
|
|
97
|
-
What an edit *can* cost you is time, not money: changing verification-relevant data moves the
|
|
98
|
-
brand `VERIFIED → UNVERIFIED` and it re-verifies.
|
|
99
|
-
|
|
100
|
-
**A failed campaign holds its reserved funds.** Funds reserved at campaign creation are released
|
|
101
|
-
for `PENDING_REVIEW` / `REJECTED` / `TCR_REGISTER_FAILED` when the campaign is **deleted**, not
|
|
102
|
-
at the moment it fails. This is deliberate, because those states are appealable and re-registerable,
|
|
103
|
-
but it means a customer who abandons failed campaigns keeps funds tied up. Deleting the dead
|
|
104
|
-
campaign frees them.
|
|
@@ -1,84 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: signalhouse-advisor
|
|
3
|
-
description: >-
|
|
4
|
-
Planning a Signal House integration: the order the platform actually enforces, which work is
|
|
5
|
-
asynchronous and how long it really takes, what the caller's role permits, and which Signal House
|
|
6
|
-
skill answers which question.
|
|
7
|
-
TRIGGER when the user asks how to build on Signal House, wants an integration plan or timeline,
|
|
8
|
-
asks "what do I need to send my first message", is scoping or estimating work, or is deciding
|
|
9
|
-
which endpoint or SDK namespace to reach for.
|
|
10
|
-
SKIP once the plan is settled and the work is one specific area. Hand off to signalhouse-setup,
|
|
11
|
-
signalhouse-10dlc, signalhouse-numbers, signalhouse-sms or signalhouse-webhooks and follow that.
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
# Planning a Signal House integration
|
|
15
|
-
|
|
16
|
-
## What cannot happen
|
|
17
|
-
|
|
18
|
-
**There is no path from zero to a sent message in one sitting.** Brand and campaign registration go
|
|
19
|
-
to external registries and carriers. Approval is measured in **days**, not minutes, and it can be
|
|
20
|
-
rejected. Any plan, estimate or demo script that ends "and then we send a test message" on day one
|
|
21
|
-
is wrong, and stating it optimistically wastes the customer's launch date rather than saving it.
|
|
22
|
-
|
|
23
|
-
**The order is enforced by the platform, not by convention.** Brand before campaign; numbers
|
|
24
|
-
attached at campaign creation; campaign `ACTIVE` before any send. A plan that discovers this at step
|
|
25
|
-
nine has to be rebuilt from step two.
|
|
26
|
-
|
|
27
|
-
**A plan is only executable if the token's role permits it.** Roles are checked server-side and
|
|
28
|
-
differ sharply: a customer `api` service user is bound to a single group, `developer` reaches
|
|
29
|
-
messaging, numbers, keys and webhooks, `billing` reaches billing only, and the `signalhouse_*` roles
|
|
30
|
-
are staff. Confirm what the authenticated caller actually is before planning work it cannot perform.
|
|
31
|
-
When the role is unknown, say so and plan against the least privilege rather than assuming `admin`.
|
|
32
|
-
|
|
33
|
-
**Nothing about cost may be stated from memory.** Fees are per group, configurable and writable.
|
|
34
|
-
`GET /billing/fees/:groupId` is the only correct answer to what something costs, and a number
|
|
35
|
-
written into a plan reads as authoritative long after it stops being true.
|
|
36
|
-
|
|
37
|
-
## The pipeline, in the order it must happen
|
|
38
|
-
|
|
39
|
-
1. **Credential and group.** A token, and the `groupId` it is scoped to. `signalhouse-setup`.
|
|
40
|
-
2. **Webhooks.** Before the first write, not after the first surprise. Most of what follows resolves
|
|
41
|
-
out of band. `signalhouse-webhooks`.
|
|
42
|
-
3. **Funded wallet.** Registration and number purchase are charged. An unfunded account fails at the
|
|
43
|
-
first billable step, which is usually the brand.
|
|
44
|
-
4. **Brand.** Submitted for verification. Days. Can be rejected, and some rejections require
|
|
45
|
-
recreating the brand rather than editing it. `signalhouse-10dlc`.
|
|
46
|
-
5. **Numbers.** These can be bought while the brand is still verifying. Buying is not gated; sending is.
|
|
47
|
-
`signalhouse-numbers`.
|
|
48
|
-
6. **Campaign.** Created **with its numbers attached**, then registered downstream. More days.
|
|
49
|
-
`signalhouse-10dlc`.
|
|
50
|
-
7. **Send.** Only once the campaign is `ACTIVE` and the number is `READY`. `signalhouse-sms`.
|
|
51
|
-
|
|
52
|
-
Steps 4 and 5 overlap. Steps 4 and 6 do not.
|
|
53
|
-
|
|
54
|
-
## Asynchronous by design
|
|
55
|
-
|
|
56
|
-
Mutating operations across brand, campaign and number return **202** and complete out of band. The
|
|
57
|
-
HTTP response means accepted, not done. This shapes the whole integration:
|
|
58
|
-
|
|
59
|
-
- **Subscribe, do not poll.** The platform's own guidance says so, and a polling loop hits rate
|
|
60
|
-
limits while still finding out late.
|
|
61
|
-
- **Every long-running step needs a persisted state machine on the caller's side.** An integration
|
|
62
|
-
that holds "waiting for brand approval" in memory loses it on the next deploy.
|
|
63
|
-
- **Design for rejection, not just delay.** Brand and campaign both have terminal failure states. A
|
|
64
|
-
flow with no path for "rejected, here is why" is unfinished.
|
|
65
|
-
|
|
66
|
-
## Which skill answers which question
|
|
67
|
-
|
|
68
|
-
| The question | Skill |
|
|
69
|
-
|---|---|
|
|
70
|
-
| How do I authenticate, what token, why a 401 | `signalhouse-setup` |
|
|
71
|
-
| How do I know when something finished | `signalhouse-webhooks` |
|
|
72
|
-
| Why is my campaign rejected or stuck, what does TCR need | `signalhouse-10dlc` |
|
|
73
|
-
| How do I find, buy, or release numbers, what do they cost | `signalhouse-numbers` |
|
|
74
|
-
| How do I send, why did a send fail, what does a message cost | `signalhouse-sms` |
|
|
75
|
-
|
|
76
|
-
If a question spans two of these, answer with the constraint first and the mechanics second. The
|
|
77
|
-
constraint is nearly always the part that changes the plan.
|
|
78
|
-
|
|
79
|
-
## Where to look it up
|
|
80
|
-
|
|
81
|
-
- **The full setup pipeline:** the Brands and Campaigns references
|
|
82
|
-
(https://app2.signalhouse.io/docs/brands, https://app2.signalhouse.io/docs/campaigns).
|
|
83
|
-
- **A first working call:** https://app2.signalhouse.io/docs/getting-started.
|
|
84
|
-
- **Current fees and balance:** the billing endpoints, read live, per group.
|
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: signalhouse-numbers
|
|
3
|
-
description: >-
|
|
4
|
-
Signal House phone numbers: the search, purchase and list flow, and what a purchase commits
|
|
5
|
-
the account to financially.
|
|
6
|
-
TRIGGER when the user is searching for, buying, listing or releasing Signal House numbers;
|
|
7
|
-
when they are scripting or bulk-buying numbers; when a purchase fails; or when they ask what
|
|
8
|
-
numbers cost or why their balance dropped.
|
|
9
|
-
SKIP for toll-free verification and short-code provisioning, for porting numbers in, and for
|
|
10
|
-
assigning an existing number to a campaign, which belongs to 10DLC registration.
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# Signal House phone numbers
|
|
14
|
-
|
|
15
|
-
## What cannot happen
|
|
16
|
-
|
|
17
|
-
**Releasing a number is irreversible.** `DELETE /number` sets the number to `RELEASED`, and
|
|
18
|
-
**nothing transitions a number out of `RELEASED`**. It cannot be reactivated (reactivation
|
|
19
|
-
requires `DEACTIVATED`), cannot be assigned to a campaign, and cannot be re-deleted. The number
|
|
20
|
-
management guide says it plainly: released numbers cannot be recovered. Treat a release request
|
|
21
|
-
as destructive and confirm it explicitly, every time.
|
|
22
|
-
|
|
23
|
-
**A bulk local purchase has no ceiling.** `POST /number` accepts a `phoneNumbers` array with a
|
|
24
|
-
minimum of 1 and **no maximum**, unlike campaign assignment, which caps at 5000. Passing a whole
|
|
25
|
-
search page buys a whole search page. If a caller asks for "some numbers", establish the count
|
|
26
|
-
before purchasing, not after.
|
|
27
|
-
|
|
28
|
-
Toll-free is different: those purchases are capped at 10 per order and additionally gated by a
|
|
29
|
-
per-group toll-free flag. The unbounded risk above is specific to local numbers.
|
|
30
|
-
|
|
31
|
-
**A number is not sendable just because it was purchased.** It has to be attached to a campaign,
|
|
32
|
-
and that campaign has to be `ACTIVE`. See the `signalhouse-10dlc` skill.
|
|
33
|
-
|
|
34
|
-
## Order of operations
|
|
35
|
-
|
|
36
|
-
1. **Search** for available numbers, filtered to what is actually needed (state, area code,
|
|
37
|
-
SMS/MMS capability). Searching and NPA/NXX lookup are **free**, with no billing call on those
|
|
38
|
-
paths, so filter properly rather than buying to find out.
|
|
39
|
-
2. **Confirm the count and the cost** before purchasing. Read current fees from
|
|
40
|
-
`GET /billing/fees/:groupId`. Do not assume a price or carry one over from a previous run.
|
|
41
|
-
3. **Purchase** the specific numbers chosen. `subgroupId` is required, and the subgroup must
|
|
42
|
-
exist and be active.
|
|
43
|
-
4. **List** to confirm what the account now owns and is paying for.
|
|
44
|
-
|
|
45
|
-
Numbers can be purchased while a brand is still verifying. There is no brand or campaign gate on
|
|
46
|
-
the purchase path. What must wait is sending, not buying.
|
|
47
|
-
|
|
48
|
-
## Spend awareness
|
|
49
|
-
|
|
50
|
-
The rule to hold: **the account is billed for what it owns, not for what it uses.**
|
|
51
|
-
|
|
52
|
-
**Purchase is charged immediately**, per number, on both the local and toll-free paths.
|
|
53
|
-
|
|
54
|
-
**Renewal is recurring, but it is environment-gated.** There is a renewal scheduler that charges a
|
|
55
|
-
per-number renewal fee on a billing date. It only runs when `ENABLE_NUMBER_BILLING_RENEWALS` is
|
|
56
|
-
enabled, and that flag is **off by default** with the real value set per environment. So:
|
|
57
|
-
|
|
58
|
-
- Never tell a customer that numbers have no ongoing cost. The mechanism exists and is the
|
|
59
|
-
intended behaviour.
|
|
60
|
-
- Never quote the renewal as definitely active either. If it matters to the answer, check the
|
|
61
|
-
environment rather than asserting.
|
|
62
|
-
- The renewal fee is applied to toll-free numbers too, despite being named for local ones.
|
|
63
|
-
|
|
64
|
-
**Repeated renewal failures delete the number.** After a configured number of failed renewal
|
|
65
|
-
attempts the number is queued for deletion, and deletion is the irreversible release above. A
|
|
66
|
-
customer whose balance is empty does not simply go unbilled; they can lose the number.
|
|
67
|
-
|
|
68
|
-
Before any purchase, be able to state how many numbers are being bought and the current
|
|
69
|
-
per-number fee, read live. If either is unknown, ask rather than buy.
|
|
70
|
-
|
|
71
|
-
Never quote a price from memory or from this file. Fees are per-group and configurable,
|
|
72
|
-
and writable via `PUT /billing/fees/:groupId`, so a number here would be both stale and
|
|
73
|
-
authoritative-looking. `GET /billing/fees/:groupId` is the only correct answer to "what does this
|
|
74
|
-
cost".
|
|
75
|
-
|
|
76
|
-
## Where to look it up
|
|
77
|
-
|
|
78
|
-
- **Search filters, NPA/NXX lookup, friendly names, per-number inbound webhook URLs, and the
|
|
79
|
-
release semantics:** the Numbers reference, https://app2.signalhouse.io/docs/numbers.
|
|
80
|
-
- **Current fees:** `GET /billing/fees/:groupId`.
|
|
81
|
-
- **Current balance before a bulk buy:** the wallet endpoints under `/billing/wallet`.
|
|
82
|
-
- **Whether a number can send:** its campaign's state, not the number's. See `signalhouse-10dlc`.
|
|
@@ -1,121 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: signalhouse-setup
|
|
3
|
-
description: >-
|
|
4
|
-
Getting a Signal House integration authenticated and wired: login vs service-user tokens, what a
|
|
5
|
-
token is scoped to, SDK initialization, and why webhooks come before the first write.
|
|
6
|
-
TRIGGER when the user is starting a Signal House integration, asks how to authenticate, asks for
|
|
7
|
-
an API key or token, is choosing a base URL, is installing or initializing the SDK, is connecting
|
|
8
|
-
Claude, Cursor or another AI client to Signal House (MCP), is getting a 401 or 403, or asks why
|
|
9
|
-
their token stopped working.
|
|
10
|
-
SKIP for message sending, 10DLC registration, number purchase and webhook event semantics, which
|
|
11
|
-
have their own skills. This one ends at "the first authenticated call succeeds".
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
# Signal House setup
|
|
15
|
-
|
|
16
|
-
## What cannot happen
|
|
17
|
-
|
|
18
|
-
**A login token cannot carry a server integration.** `POST /auth` returns a **short-lived session
|
|
19
|
-
JWT**, measured in hours. It is the right token for a user acting in a session and the wrong token
|
|
20
|
-
for anything that runs unattended. A cron job built on a login token works all afternoon and fails
|
|
21
|
-
overnight.
|
|
22
|
-
|
|
23
|
-
Both lifetimes are set per environment (`JWT_USER_EXPIRES_IN`, `JWT_SYSTEM_EXPIRES_IN`), so treat
|
|
24
|
-
the session token as short and the service token as long, and read the exact values from the
|
|
25
|
-
Authentication guide or the environment rather than quoting a number to a customer.
|
|
26
|
-
|
|
27
|
-
**A service user cannot be bootstrapped from nothing.** `POST /user/serviceuser` needs an existing
|
|
28
|
-
group and a token that is already privileged enough to mint one. The first credential in a new
|
|
29
|
-
integration comes from a human logging in (including approving an OAuth connection, below) or from
|
|
30
|
-
Signal House provisioning it, not from an API call made with no credential.
|
|
31
|
-
|
|
32
|
-
**`role: "signalhouse_api"` is not available to customers.** The two roles `POST /user/serviceuser`
|
|
33
|
-
accepts are `api` (customer key, scoped to one `groupId`) and `signalhouse_api` (internal, requires
|
|
34
|
-
`signalhouse_admin` credentials). A customer caller asking for the internal role gets a **403**. If
|
|
35
|
-
an integration seems to need it, the requirement is wrong.
|
|
36
|
-
|
|
37
|
-
**The API key is shown once.** The token is signed and returned at creation and never stored on the
|
|
38
|
-
user record, so no endpoint can hand it back. Losing it means creating another service user, not
|
|
39
|
-
recovering the old key.
|
|
40
|
-
|
|
41
|
-
**A group under compliance rejection cannot create API keys at all.** Service-user creation is gated
|
|
42
|
-
on the group's compliance state and fails with a group-rejected error rather than a validation error.
|
|
43
|
-
Staff roles are exempt. When key creation fails for one group and works for another, check the
|
|
44
|
-
account's standing before debugging the request.
|
|
45
|
-
|
|
46
|
-
**Being authenticated does not mean being able to send.** Setup ends with a working credential.
|
|
47
|
-
Sending additionally requires a verified brand, an `ACTIVE` campaign, and a number in `READY` status
|
|
48
|
-
on it. See `signalhouse-10dlc`.
|
|
49
|
-
|
|
50
|
-
## Order of operations
|
|
51
|
-
|
|
52
|
-
1. **Get a token.** Human session → `POST /auth`, short-lived. Server integration → a service user,
|
|
53
|
-
long-lived. Do not build a server integration on a login token and plan to "refresh it later".
|
|
54
|
-
2. **Know the group.** A customer service user (`role: "api"`) is bound to one `groupId`, an
|
|
55
|
-
8-character id beginning with `G`. That scoping is what limits the damage of a leaked
|
|
56
|
-
key, so one key per group is the design, not an inconvenience to work around.
|
|
57
|
-
3. **Initialize the SDK** with `apiKey` and `baseUrl`. The `apiKey` is the default credential on
|
|
58
|
-
every request; `options: { token }` overrides it per call, which is how an app acting for many
|
|
59
|
-
users should work rather than reinitializing the SDK per user.
|
|
60
|
-
4. **Make one read call** and check the envelope before writing anything.
|
|
61
|
-
5. **Register webhooks before the first write.** Brand registration, campaign registration, number
|
|
62
|
-
purchase and message delivery all resolve out of band, minutes to days later. An integration
|
|
63
|
-
without webhooks discovers outcomes by polling, burns rate limit doing it, and still finds out
|
|
64
|
-
late. See `signalhouse-webhooks`.
|
|
65
|
-
|
|
66
|
-
## Connecting an AI client (MCP)
|
|
67
|
-
|
|
68
|
-
Signal House runs a hosted MCP server at `https://mcp.signalhouse.io/mcp`. It holds no credentials
|
|
69
|
-
of its own: every call is forwarded to the API with the caller's own token, so an agent can do
|
|
70
|
-
exactly what that token can do and nothing more.
|
|
71
|
-
|
|
72
|
-
- **Claude (web, Desktop, mobile): connect with OAuth.** Settings > Connectors > Add custom
|
|
73
|
-
connector, paste the URL, leave the client ID and secret blank, then log in to Signal House and
|
|
74
|
-
approve. No API key is copied anywhere. This is the path to recommend to a person.
|
|
75
|
-
- **Clients configured by file or command (Claude Code, Cursor and similar):** send an API key as a
|
|
76
|
-
bearer header, e.g.
|
|
77
|
-
`claude mcp add --transport http signalhouse https://mcp.signalhouse.io/mcp --header "Authorization: Bearer <API key>"`.
|
|
78
|
-
Claude Code can also do the OAuth flow: add it without the header and authenticate from `/mcp`.
|
|
79
|
-
|
|
80
|
-
What an OAuth connection can and cannot do:
|
|
81
|
-
|
|
82
|
-
- **It acts as the user who approved it, with that user's full role.** Scopes are not enforced, so
|
|
83
|
-
do not tell a customer a connection is "read-only" or limited to part of the account.
|
|
84
|
-
- **It cannot mint credentials or manage the login.** Routes under `/user` and `/auth` refuse a
|
|
85
|
-
connector token with a **403**, so an agent on an OAuth connection cannot create service users or
|
|
86
|
-
API keys. A 403 there is by design, not a bug to work around; create keys in the portal.
|
|
87
|
-
- **It is revoked by the user**, in the portal under Settings > Security > Connected Applications.
|
|
88
|
-
After that the client has to reconnect.
|
|
89
|
-
|
|
90
|
-
For an unattended server integration, the rules above still hold: use a service-user API key, not
|
|
91
|
-
an OAuth connection, which exists for a person working through an AI client.
|
|
92
|
-
|
|
93
|
-
## Reading the response
|
|
94
|
-
|
|
95
|
-
The SDK returns an **envelope**, and most failures arrive inside it rather than as an exception:
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
{ success: true|false, data: <payload>, error: <body>, status: <http status> }
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
- Branch on `response.success` and `response.status`, not on a try/catch alone.
|
|
102
|
-
- **Rate limiting is a `429` in the envelope**, not a throw. Detect it as `response.status === 429`
|
|
103
|
-
and back off; matching on the error string is brittle.
|
|
104
|
-
- Client-side validation failures DO throw (`SignalHouseValidationError`). Those are not retryable,
|
|
105
|
-
and retrying an invalid payload just spends the retry budget.
|
|
106
|
-
- A `401` means the token expired or was revoked. Re-authenticate; do not retry the same token.
|
|
107
|
-
|
|
108
|
-
Response shapes are nested differently per endpoint and the nesting is not guessable. Read the
|
|
109
|
-
current shape from the API reference rather than assuming it matches a sibling endpoint.
|
|
110
|
-
|
|
111
|
-
## Where to look it up
|
|
112
|
-
|
|
113
|
-
- **Auth flows, service users, the full role table, token practice:** the Authentication reference,
|
|
114
|
-
https://app2.signalhouse.io/docs/authentication.
|
|
115
|
-
- **The OAuth connection flow:** https://app2.signalhouse.io/docs/oauth.
|
|
116
|
-
- **First working call end to end:** https://app2.signalhouse.io/docs/getting-started.
|
|
117
|
-
- **Envelope shapes, error classes and status codes:** https://app2.signalhouse.io/docs/error-handling.
|
|
118
|
-
- **Backoff, batching and pagination:** https://app2.signalhouse.io/docs/rate-limits.
|
|
119
|
-
- **What a role is allowed to do:** the role table in the Authentication reference. Roles are
|
|
120
|
-
checked server-side, so a plan that assumes more access than the token has fails at the call, not
|
|
121
|
-
earlier.
|