@signalhousellc/sdk 1.5.0 → 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.
Files changed (54) hide show
  1. package/README.md +5 -56
  2. package/index.d.ts +1 -0
  3. package/index.js +2 -0
  4. package/package.json +32 -34
  5. package/voice-browser.d.ts +1 -0
  6. package/voice-browser.js +2 -0
  7. package/warn.js +7 -0
  8. package/webhooks.d.ts +1 -0
  9. package/webhooks.js +2 -0
  10. package/scripts/install-skills.mjs +0 -329
  11. package/skills/VENDORED.json +0 -22
  12. package/skills/signalhouse-10dlc/SKILL.md +0 -172
  13. package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
  14. package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
  15. package/skills/signalhouse-advisor/SKILL.md +0 -84
  16. package/skills/signalhouse-numbers/SKILL.md +0 -82
  17. package/skills/signalhouse-setup/SKILL.md +0 -121
  18. package/skills/signalhouse-sms/SKILL.md +0 -81
  19. package/skills/signalhouse-webhooks/SKILL.md +0 -148
  20. package/src/SignalHouseSDK.js +0 -201
  21. package/src/domains/Agents.js +0 -987
  22. package/src/domains/Auth.js +0 -225
  23. package/src/domains/Billing.js +0 -264
  24. package/src/domains/Brands.js +0 -508
  25. package/src/domains/Campaigns.js +0 -691
  26. package/src/domains/Dnc.js +0 -168
  27. package/src/domains/Groups.js +0 -187
  28. package/src/domains/Landings.js +0 -237
  29. package/src/domains/Messages.js +0 -609
  30. package/src/domains/Notifications.js +0 -62
  31. package/src/domains/Numbers.js +0 -572
  32. package/src/domains/Onboarding.js +0 -128
  33. package/src/domains/Registrations.js +0 -246
  34. package/src/domains/Shortlinks.js +0 -80
  35. package/src/domains/Subgroups.js +0 -136
  36. package/src/domains/Subscriptions.js +0 -146
  37. package/src/domains/Templates.js +0 -403
  38. package/src/domains/Tickets.js +0 -100
  39. package/src/domains/Users.js +0 -228
  40. package/src/domains/Voice.js +0 -41
  41. package/src/domains/Webhooks.js +0 -125
  42. package/src/domains/voice/Analytics.js +0 -82
  43. package/src/domains/voice/CallLogs.js +0 -111
  44. package/src/domains/voice/Calls.js +0 -118
  45. package/src/domains/voice/GlobalVoiceSettings.js +0 -54
  46. package/src/domains/voice/NumberRoutes.js +0 -82
  47. package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
  48. package/src/domains/voice/SipProfiles.js +0 -203
  49. package/src/domains/voice/SipTrunks.js +0 -203
  50. package/src/domains/voice/Tokens.js +0 -96
  51. package/src/domains/voice/browser/Call.js +0 -366
  52. package/src/domains/voice/browser/Device.js +0 -484
  53. package/src/domains/voice/browser/index.js +0 -17
  54. package/src/webhooks/verifySignature.js +0 -66
@@ -1,609 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- /**
8
- * Serialise regionScopes for the query string: an array of branches becomes JSON, a string is passed through.
9
- * @param {Object} filters - Query filters that may carry regionScopes
10
- * @returns {Object} - The filters with regionScopes JSON-encoded when present
11
- */
12
- function withRegionScopes(filters) {
13
- if (filters.regionScopes === undefined) return filters;
14
- const regionScopes = typeof filters.regionScopes === "string" ? filters.regionScopes : JSON.stringify(filters.regionScopes);
15
- return { ...filters, regionScopes };
16
- }
17
-
18
- export class Messages {
19
- constructor(client, multipartClient, enableAdmin) {
20
- this.client = client;
21
- this.multipartClient = multipartClient;
22
- this.enableAdmin = enableAdmin;
23
- }
24
-
25
- /**
26
- * Estimate regional SMS/MMS retail cost; no charge or send. A Canadian sender requires a Ready Canadian sender and
27
- * Canadian or US recipients, and is unavailable unless Canada is enabled for the environment. A +44 (UK) sender
28
- * estimates SMS to GB mobiles only and returns region "GB"; while UK sending is disabled for the environment a UK
29
- * sender is refused with a 400. The sender may also be a READY alphanumeric sender ID (e.g. "ACME"; UK recipients,
30
- * SMS only); its estimate counts the "\nOpt out: sihou.io/o/{code}" footer the server appends to every such message.
31
- * @async
32
- * @param {Object} params - Sender, up to 100 recipients (10-15 digits each), messageBody and request options.
33
- * @returns {Promise<SdkResponse<any>>} - Per-recipient rates and total in microdollars; unknown carriers use the upper fallback.
34
- */
35
- async estimateMessage({ senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType = "SMS", options = {} }) {
36
- return this.client("/message/estimate", { method: "POST", body: { senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType }, ...options });
37
- }
38
-
39
- /**
40
- * Get a list of messages with optional filters and pagination parameters
41
- * @async
42
- * @roles api, admin, developer, billing, user
43
- * @param {Object} params - The parameters for getting messages
44
- * @param {string} [params.id] - Filter messages by their unique ID
45
- * @param {string} [params.campaignId] - Filter messages by the ID of the associated campaign
46
- * @param {string} [params.brandId] - Filter messages by the ID of the associated brand
47
- * @param {string} [params.subgroupId] - Filter messages by the ID of the associated subgroup
48
- * @param {string} [params.groupId] - Filter messages by the ID of the associated group
49
- * @param {string|string[]} [params.registrationId] - Filter to messages attributed to these registrations. Cannot be combined with campaignId; each id must belong to the group. Accepts a single value or an array.
50
- * @param {string} [params.status] - Filter messages by their status (ENQUEUED, DEQUEUED, SENT, FAILED, DELIVERED)
51
- * @param {string} [params.direction] - Filter messages by their direction (INBOUND, OUTBOUND)
52
- * @param {string|string[]} [params.messageType] - Filter messages by their type. Accepts a single value or an array (e.g. ["SMS", "MMS"]). Allowed values: SMS, MMS, RCS, WHATSAPP, VIBER, P2P. When omitted, defaults to all non-P2P types.
53
- * @param {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, virtualLongCode, tollFree, shortCode, p2p. Each message records its channel when it is saved, and this filters on that stored value; older messages from before this feature have no channel and count as tenDLC. Ignored when matchAny is true (matchAny takes precedence).
54
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Accepted whether or not the environment serves hourly analytics.
55
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Accepted whether or not the environment serves hourly analytics.
56
- * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (a message matches ANY of them) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
57
- * @param {string} [params.carrier] - Filter messages by the carrier used for sending
58
- * @param {string|string[]} [params.sentimentLabel] - Filter messages by sentiment bucket. Accepts a single value or an array (e.g. ["positive", "negative"]). Allowed values: positive, neutral, negative. Applied as the sentimentScore range the ±25 label threshold produces, so unscored messages match no bucket and outbound messages (never scored) are excluded.
59
- * @param {string|string[]} [params.errorCode] - Filter FAILED messages by Signal House error code (single value or array). "OUT" is the campaign opt-out, displayed as RECIPIENT_OPTED_OUT. Carrier codes are not filterable here; they live inside successOrFailureReason.
60
- * @param {string|string[]} [params.phoneNumber] - Filter messages by a business number on either side of the message. Accepts a single value or an array; OR'd with campaignId/brandId when matchAny is true
61
- * @param {string} [params.senderPhoneNumber] - Filter messages by the sender's 5-6 digit Short Code or 10+ digit phone number. Use % as a wildcard for a partial match (e.g. "%1234" matches numbers ending in 1234); a plain value is an exact match. 3-15 digits required alongside any %.
62
- * @param {string} [params.recipientPhoneNumber] - Filter messages by the recipient's phone number. Use % as a wildcard for a partial match (e.g. "%1234" matches numbers ending in 1234); a plain value is an exact match. 3-15 digits required alongside any %.
63
- * @param {string} [params.startDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode
64
- * @param {string} [params.endDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back
65
- * @param {string} [params.sortField] - The field to sort the messages by (createdAt, segmentCount, status, sentimentScore)
66
- * @param {string} [params.sortOrder] - The order to sort the messages (asc, desc)
67
- * @param {number} [params.page] - The page number for pagination
68
- * @param {number} [params.limit] - The number of messages per page
69
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
70
- * @param {RequestOptions} [params.options] - Additional options for the request
71
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the list of messages. Inbound messages also carry
72
- * sentimentScore (-100..100, null when unscored), sentimentLabel ("positive"|"neutral"|"negative", null when
73
- * sentimentScore is null) and sentimentScoredAt. Outbound messages are never scored.
74
- */
75
- async getMessages({
76
- id,
77
- campaignId,
78
- brandId,
79
- subgroupId,
80
- groupId,
81
- registrationId,
82
- phoneNumber,
83
- senderPhoneNumber,
84
- recipientPhoneNumber,
85
- status,
86
- direction,
87
- messageType,
88
- channel,
89
- region,
90
- regionScopes,
91
- matchAny,
92
- carrier,
93
- sentimentLabel,
94
- errorCode,
95
- startDate,
96
- endDate,
97
- sortField,
98
- sortOrder,
99
- page,
100
- limit,
101
- dateBounds,
102
- options = {},
103
- }) {
104
- const filters = { id, campaignId, brandId, subgroupId, groupId, registrationId, phoneNumber, senderPhoneNumber, recipientPhoneNumber, status, direction, messageType, channel, region, regionScopes, matchAny, carrier, sentimentLabel, errorCode, startDate, endDate, sortField, sortOrder, page, limit, dateBounds };
105
- const queryString = this.client._getQueryString(withRegionScopes(filters));
106
- return this.client(`/message${queryString}`, { method: "GET", ...options });
107
- }
108
-
109
- /**
110
- * Fetch the latest upstream carrier delivery report for a set of messages by ID (SHGHL-1856).
111
- * Useful for reconciling messages stuck in a non-terminal state. Outbound SMS and MMS messages sent from numbers on
112
- * the carrier whose delivery logs we read are looked up there (the logs are kept about 48 hours); every other message,
113
- * including P2P messages and messages sent from numbers on other carriers, is returned with its stored status and
114
- * upstreamReportAvailable false. The request fails with a 500 when the sending numbers can't be read.
115
- * @async
116
- * @roles api, admin, developer, billing, user
117
- * @param {Object} params - The parameters for fetching delivery reports
118
- * @param {string[]} params.messageIds - The message IDs to fetch carrier delivery reports for (1-100)
119
- * @param {RequestOptions} [params.options] - Additional options for the request
120
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to an array of carrier delivery reports
121
- */
122
- async getDeliveryReports({ messageIds, options = {} }) {
123
- this.client._require({ messageIds });
124
- return this.client(`/message/delivery-report`, {
125
- method: "POST",
126
- body: { messageIds },
127
- ...options,
128
- });
129
- }
130
-
131
- /**
132
- * Get aggregated analytics for messages with optional filters
133
- * @async
134
- * @roles api, admin, developer, billing, user
135
- * @param {Object} params - The parameters for getting analytics
136
- * @param {string} [params.groupId] - Filter analytics by the ID of the associated group
137
- * @param {string|string[]} [params.subgroupId] - Filter analytics by the ID of the associated subgroup. Accepts a single value, an array, or a comma-separated string.
138
- * @param {string|string[]} [params.brandId] - Filter analytics by the ID of the associated brand. Accepts a single value, an array, or a comma-separated string.
139
- * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
140
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
141
- * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
142
- * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
143
- * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
144
- * @param {string} [params.startDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode
145
- * @param {string} [params.endDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back
146
- * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (match ANY) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
147
- * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
148
- * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, virtualLongCode, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here (matched by carrier). Accepts a single value or an array. Ignored when matchAny is true (matchAny takes precedence).
149
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
150
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
151
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
152
- * @param {RequestOptions} [params.options] - Additional options for the request
153
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the analytics data. Also includes inbound-message
154
- * sentiment for the requested scope: sentimentScore (volume-weighted average of every scored inbound message
155
- * in range, -100..100, null when nothing was scored), sentimentLabel ("positive"|"neutral"|"negative", null
156
- * when sentimentScore is null), sentimentScoredCount, sentimentPositive, sentimentNeutral, sentimentNegative.
157
- * plus the same six per message type under smsSentiment*, mmsSentiment* and p2pSentiment* prefixes. Every
158
- * score is divided server-side and the raw sums are never returned: a score is an average and must never be
159
- * summed or re-averaged across types, rows or responses. To weight a subset of message types, pass
160
- * messageType and read sentimentScore.
161
- */
162
- async getAnalytics({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, region, regionScopes, messageType, matchAny, dateBounds, options = {} }) {
163
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, region, regionScopes, messageType, matchAny, dateBounds };
164
- const queryString = this.client._getQueryString(withRegionScopes(filters));
165
- return this.client(`/message/analytics${queryString}`, { method: "GET", ...options });
166
- }
167
-
168
- /**
169
- * Get detailed analytics snapshot records for charting and aggregation
170
- * @async
171
- * @roles api, admin, developer, billing, user
172
- * @param {Object} params - The parameters for getting detailed analytics
173
- * @param {string} [params.groupId] - Filter analytics by the ID of the associated group
174
- * @param {string|string[]} [params.subgroupId] - Filter analytics by the ID of the associated subgroup. Accepts a single value, an array, or a comma-separated string.
175
- * @param {string|string[]} [params.brandId] - Filter analytics by the ID of the associated brand. Accepts a single value, an array, or a comma-separated string.
176
- * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
177
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
178
- * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
179
- * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
180
- * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
181
- * @param {string} [params.startDate] - ISO-8601 date or timestamp. It is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode, then floored to the start of its hour at either granularity, because the hourly cube is keyed by hour and a mid-hour start would drop that hour's bucket.
182
- * @param {string} [params.endDate] - ISO-8601 date or timestamp. At day granularity it is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back; at hour granularity it is honoured as given.
183
- * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
184
- * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, virtualLongCode, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here. Accepts a single value or an array.
185
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
186
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
187
- * @param {("day"|"hour")} [params.granularity] - Time-bucket grain of the byDate rows. Omit for day (each row's _id is a "YYYY-MM-DD" date). "hour" buckets by hour (each row's _id is a "YYYY-MM-DD HH:MM:SS" UTC hour) and is capped to a 7-day span. Only accepted where the environment serves hourly analytics; elsewhere any value, including "day", is rejected with a 400 -- omit the parameter unless hour grain is wanted.
188
- * @param {("carrier"|"carrierFamily")} [params.breakdown] - Adds a byBreakdown time × dimension series to the response ({ dimension, rows }: each row is one byDate bucket (_id) for one carrier or carrier family (key), over the top 50 keys by volume, excluding P2P) and caps the span at 31 days. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
189
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
190
- * @param {RequestOptions} [params.options] - Additional options for the request
191
- * @returns {Promise<SdkResponse<Array>>} - A promise that resolves to an array of analytics snapshot records. cardTotals and
192
- * every byDate/byPhoneNumber/byCarrier row also carry that row's own inbound-message sentiment: sentimentScore
193
- * (volume-weighted average, -100..100, null when nothing in that row's scope was scored), sentimentLabel,
194
- * sentimentScoredCount, sentimentPositive, sentimentNeutral, sentimentNegative. The fields are always present;
195
- * plus the same six per message type under smsSentiment*, mmsSentiment* and p2pSentiment* prefixes. Every
196
- * score is divided server-side and the raw sums are never returned: a score is an average and must never be
197
- * summed or re-averaged across types, rows or responses.
198
- */
199
- async getAnalyticsDetail({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, region, regionScopes, messageType, granularity, breakdown, dateBounds, options = {} }) {
200
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, region, regionScopes, messageType, granularity, breakdown, dateBounds };
201
- const queryString = this.client._getQueryString(withRegionScopes(filters));
202
- return this.client(`/message/analytics/detail${queryString}`, { method: "GET", ...options });
203
- }
204
-
205
- /**
206
- * Get per-minute send throughput (peak segments per minute, sending minutes, minutes at a ceiling) for a
207
- * campaign, brand, or group, per time bucket and per carrier family. Measured from SENT transitions at
208
- * campaign × carrier-family grain -- the grain carrier ceilings are enforced at -- so a peak here is the
209
- * figure a ceiling is compared against. Only accepted where the environment serves hourly analytics;
210
- * elsewhere the request is rejected with a 400.
211
- * @async
212
- * @roles api, admin, developer, billing, user
213
- * @param {Object} params - The parameters for the throughput read
214
- * @param {string} params.groupId - The group to scope the read to (required)
215
- * @param {string|string[]} [params.brandId] - Brand scope. Accepts a single value, an array, or a comma-separated string.
216
- * @param {string|string[]} [params.campaignId] - Campaign scope; wins over brandId. Accepts a single value, an array, or a comma-separated string.
217
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). Accepts a single value or an array.
218
- * @param {string|string[]} [params.carrierFamily] - Carrier-family filter (ATT, TMobile, Verizon, USCellular, ...). Accepts a single value, an array, or a comma-separated string.
219
- * @param {string} params.startDate - ISO-8601 date or timestamp. It is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode, then floored to the start of its hour at hour granularity and of its minute at day granularity (the cube is keyed by minute).
220
- * @param {string} params.endDate - ISO-8601 date or timestamp. At hour granularity it is honoured as given; at day granularity it is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back. The span is capped at 35 days (the retention of the per-minute data).
221
- * @param {("hour"|"day")} [params.granularity] - Bucket grain of the byDate and byBreakdown rows. Omit for hour (each row's _id is a "YYYY-MM-DD HH:MM:SS" UTC hour, span capped at 7 days); "day" buckets by calendar day on the end bound's offset.
222
- * @param {number} [params.ceiling] - Segments-per-minute ceiling. When given, every row also reports minutesAtCeiling (sending minutes at or above it); otherwise minutesAtCeiling is null.
223
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
224
- * @param {RequestOptions} [params.options] - Additional options for the request
225
- * @returns {Promise<SdkResponse<any>>} - `{ totals, byDate, byCarrierFamily, byBreakdown: { dimension: "carrierFamily", rows } }`. Every row carries segments, messages, peakSegmentsPerMinute, peakMessagesPerMinute, peakMinute (UTC "YYYY-MM-DD HH:MM:SS", null when no traffic), sendingMinutes, averageSegmentsPerSendingMinute and minutesAtCeiling.
226
- */
227
- async getAnalyticsThroughput({ groupId, brandId, campaignId, registrationId, carrierFamily, startDate, endDate, granularity, ceiling, dateBounds, options = {} }) {
228
- const filters = { groupId, brandId, campaignId, registrationId, carrierFamily, startDate, endDate, granularity, ceiling, dateBounds };
229
- const queryString = this.client._getQueryString(filters);
230
- return this.client(`/message/analytics/throughput${queryString}`, { method: "GET", ...options });
231
- }
232
-
233
- /**
234
- * Get filter dropdown options (subgroups, brands, campaigns, phone numbers, carriers) for the Analytics page,
235
- * scoped to a single group. Sourced from ClickHouse — only items with at least one message are returned.
236
- * @async
237
- * @roles api, admin, developer, billing, user
238
- * @param {Object} params - The parameters for getting analytics filter options
239
- * @param {string} params.groupId - The ID of the group whose filter options to load
240
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
241
- * @param {RequestOptions} [params.options] - Additional options for the request
242
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to { subgroups, brands, campaigns, phoneNumbers, carriers }. Each phone number carries type (TOLL_FREE, SHORT_CODE, ALPHANUMERIC, VIRTUAL_LONG_NUMBER, ...) and country (ISO-2), null when unknown: TOLL_FREE, SHORT_CODE and ALPHANUMERIC are channels by type; any other US number is 10DLC and a non-US one is a Virtual Long Code. `carriers` is a plain array of carrier name strings.
243
- */
244
- async getAnalyticsFilterOptions({ groupId, region, options = {} }) {
245
- const filters = { groupId, region };
246
- const queryString = this.client._getQueryString(filters);
247
- return this.client(`/message/analytics/filter-options${queryString}`, { method: "GET", ...options });
248
- }
249
-
250
- /**
251
- * Get a paginated breakdown of message metrics grouped by subgroup. Each row carries the
252
- * full set of sms/mms/p2p metric columns so the caller can apply channel toggles client-side.
253
- * @async
254
- * @roles api, admin, developer, billing, user
255
- * @param {Object} params
256
- * @param {string} params.groupId - The Group ID
257
- * @param {string|string[]} [params.subgroupId]
258
- * @param {string|string[]} [params.brandId]
259
- * @param {string|string[]} [params.campaignId]
260
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
261
- * @param {string|string[]} [params.phoneNumber]
262
- * @param {string|string[]} [params.carrier]
263
- * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
264
- * @param {string} [params.startDate]
265
- * @param {string} [params.endDate]
266
- * @param {number} [params.page=1]
267
- * @param {number} [params.limit=50] - max 50 per page
268
- * @param {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/virtualLongCode/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s).
269
- * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
270
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
271
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
272
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
273
- * @param {RequestOptions} [params.options]
274
- * @returns {Promise<SdkResponse<any>>} - { rows, totalCount, page, limit }. Each row carries sms/mms/p2p metric columns plus `smsOptOuts` and `mmsOptOuts` from the DNC analytics MV (P2P has no opt-outs).
275
- * Each row also carries that subgroup's inbound-message sentiment: `sentimentScore` (volume-weighted average of every scored inbound message in that subgroup, -100..100, null when nothing was scored), `sentimentLabel`, `sentimentScoredCount`, `sentimentPositive`, `sentimentNeutral`, `sentimentNegative`, plus the same six per message type under `smsSentiment*`, `mmsSentiment*` and `p2pSentiment*` prefixes. The score is derived server-side and must never be re-averaged across rows — combine the counts, not the scores.
276
- */
277
- async getAnalyticsBySubgroup({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, messageType, dateBounds, options = {} }) {
278
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, messageType, dateBounds };
279
- const queryString = this.client._getQueryString(withRegionScopes(filters));
280
- return this.client(`/message/analytics/by-subgroup${queryString}`, { method: "GET", ...options });
281
- }
282
-
283
- /**
284
- * Get a paginated breakdown of failed messages grouped by error code.
285
- * Each row contains per-channel (sms/mms/p2p) error counts plus an enriched description.
286
- * @async
287
- * @roles api, admin, developer, billing, user
288
- * @param {Object} params
289
- * @param {string} params.groupId - The Group ID
290
- * @param {string|string[]} [params.subgroupId]
291
- * @param {string|string[]} [params.brandId]
292
- * @param {string|string[]} [params.campaignId]
293
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
294
- * @param {string|string[]} [params.phoneNumber]
295
- * @param {string|string[]} [params.carrier]
296
- * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
297
- * @param {string} [params.startDate]
298
- * @param {string} [params.endDate]
299
- * @param {number} [params.page=1]
300
- * @param {number} [params.limit=50] - max 50 per page
301
- * @param {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/virtualLongCode/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s); when one channel is selected, totalErrors reflects only that channel.
302
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
303
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
304
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
305
- * @param {string} [params.errorCode] - Narrow the breakdown to a single failure reason: a numeric Infobip carrier code (as a string, e.g. "607"), the Signal House campaign-opt-out code "OUT", or a no-code failure class (other, moderation, att_limit, p2p_stop, campaign_opt_out, dnc_blocked, bind_hold_expired). Omitted = every reason.
306
- * @param {RequestOptions} [params.options]
307
- * @returns {Promise<SdkResponse<any>>} - { rows, totalCount, totalErrors: { sms, mms, p2p, all }, page, limit }
308
- */
309
- async getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds, errorCode, options = {} }) {
310
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds, errorCode };
311
- const queryString = this.client._getQueryString(withRegionScopes(filters));
312
- return this.client(`/message/analytics/by-error-code${queryString}`, { method: "GET", ...options });
313
- }
314
-
315
- /**
316
- * Get aggregated DNC (Do Not Contact) opt-out analytics with optional filters
317
- * @async
318
- * @roles api, admin, developer, billing, user
319
- * @param {Object} params - The parameters for getting DNC analytics
320
- * @param {string} [params.groupId] - Filter by the ID of the associated group
321
- * @param {string} [params.subgroupId] - Filter by the ID of the associated subgroup
322
- * @param {string} [params.brandId] - Filter by the ID of the associated brand
323
- * @param {string} [params.campaignId] - Filter by the ID of the associated campaign
324
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
325
- * @param {string} [params.phoneNumber] - Filter by the phone number
326
- * @param {string} [params.carrier] - Filter by the carrier
327
- * @param {string} [params.startDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode
328
- * @param {string} [params.endDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back
329
- * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
330
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
331
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
332
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
333
- * @param {RequestOptions} [params.options] - Additional options for the request
334
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, bySenderNumber, byCampaign, bySubgroup, byType, byCarrier, byKeyword). bySenderNumber ({ senderPhoneNumber, total, sms, mms }) attributes each opt-out to the first business number that received it, so it is unchanged by later campaign moves and START replies. byCampaign ({ campaignId, ... }) counts campaign-scoped opt-outs only, by the campaign at the time of the STOP; subgroup-scoped opt-outs (non-US recipients) are never attributed to a campaign and appear under bySubgroup ({ subgroupId, ... }) instead. byType ({ messageType, total }) splits SMS/MMS. byKeyword breaks opt-outs down by the normalized keyword that revoked consent ({ optOutKeyword, total, sms, mms }); opt-outs recorded before keyword capture shipped appear as a single optOutKeyword: null bucket ("not recorded"). The distinct keyword set is open-ended (campaigns register their own keywords beyond the mandatory floor) — render top-N plus Other, never a fixed list.
335
- */
336
- async getDncAnalytics({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, startDate, endDate, channel, region, regionScopes, dateBounds, options = {} }) {
337
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, startDate, endDate, channel, region, regionScopes, dateBounds };
338
- const queryString = this.client._getQueryString(withRegionScopes(filters));
339
- return this.client(`/message/dnc/analytics${queryString}`, { method: "GET", ...options });
340
- }
341
-
342
- /**
343
- * Get paginated Do Not Call records with optional filters
344
- * @async
345
- * @roles api, admin, developer, billing, user
346
- * @param {Object} params - The parameters for getting DNC records
347
- * @param {string} [params.groupId] - Filter by the ID of the associated group
348
- * @param {string} [params.subgroupId] - Filter by the ID of the associated subgroup
349
- * @param {string} [params.brandId] - Filter by the ID of the associated brand
350
- * @param {string} [params.campaignId] - Filter by the ID of the associated campaign
351
- * @param {string|string[]} [params.registrationId] - Filter to traffic attributed to these registrations (hourly analytics only; a 400 while hourly reads are off). A phoneNumber filter takes precedence. Accepts a single value or an array.
352
- * @param {string} [params.phoneNumber] - Filter by the phone number
353
- * @param {string} [params.carrier] - Filter by the carrier
354
- * @param {string} [params.startDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode
355
- * @param {string} [params.endDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back
356
- * @param {number} [params.page] - Page number for pagination
357
- * @param {number} [params.limit] - Number of records per page
358
- * @param {string} [params.sortField] - Field to sort by
359
- * @param {string} [params.sortOrder] - Sort direction (asc, desc)
360
- * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
361
- * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
362
- * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
363
- * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
364
- * @param {RequestOptions} [params.options] - Additional options for the request
365
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the paginated DNC records. Each record carries senderPhoneNumber — the first business number that received the opt-out (set once, never changed by a later STOP or a campaign move; the same value as phoneNumber) — optOutKeyword — the normalized keyword that revoked consent (e.g. "stop", "opt out"; a repeat opt-out records the most recent word), null for opt-outs recorded before keyword capture shipped — and carrierFamily, the resolved carrier family of the recipient number (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, Standard, IceWireless), copied from the inbound message that triggered the opt-out. campaignId is null on subgroup-scoped records (non-US recipients).
366
- */
367
- async getDncRecords({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, region, regionScopes, dateBounds, options = {} }) {
368
- const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, region, regionScopes, dateBounds };
369
- const queryString = this.client._getQueryString(withRegionScopes(filters));
370
- return this.client(`/message/dnc${queryString}`, { method: "GET", ...options });
371
- }
372
-
373
- /**
374
- * Send an SMS message to one or more recipient phone numbers
375
- *
376
- * The response reports the send outcome with three fields so callers do not have to inspect
377
- * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
378
- * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
379
- * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
380
- * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
381
- * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
382
- * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
383
- * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
384
- * failures with no assigned code) that is also included on the FAILED status-callback payload.
385
- * @async
386
- * @roles api, admin, developer, billing, user
387
- * @param {Object} params - The parameters for sending an SMS message
388
- * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from, or a READY alphanumeric sender ID (e.g. "ACME"; UK recipients and SMS only). Every message from an alphanumeric sender gets "\nOpt out: sihou.io/o/{code}" appended by the server, counted in segments.
389
- * @param {string|string[]} params.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
390
- * @param {string} params.messageBody - The body of the SMS message
391
- * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
392
- * @param {boolean} [params.enableShortlink=false] - Whether to enable shortlink in the message
393
- * @param {boolean} [params.filterLandlinesAndInactiveNumbers=false] - Whether to filter out landline and inactive numbers before sending
394
- * @param {RequestOptions} [params.options] - Additional options for the request
395
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the response data from the server
396
- */
397
- async sendSMS({ senderPhoneNumber, recipientPhoneNumbers, messageBody, statusCallbackUrl, enableShortlink = false, filterLandlinesAndInactiveNumbers = false, options = {} }) {
398
- this.client._require({ senderPhoneNumber, recipientPhoneNumbers, messageBody });
399
- return this.client(`/message/sms`, {
400
- method: "POST",
401
- body: { senderPhoneNumber, recipientPhoneNumber: recipientPhoneNumbers, messageBody, statusCallbackUrl, enableShortlink, ...(filterLandlinesAndInactiveNumbers && { filterLandlinesAndInactiveNumbers }) },
402
- ...options,
403
- });
404
- }
405
-
406
- /**
407
- * Send a P2P message via Rogue Mobile SMPP
408
- * @async
409
- * @roles api, admin, developer, billing, user
410
- * @param {Object} params - The parameters for sending a P2P message
411
- * @param {string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
412
- * @param {string} params.messageBody - The body of the P2P message
413
- * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
414
- * @param {string} [params.groupId] - Explicit group to send from. Defaults to the group in your auth context.
415
- * @param {string} [params.subgroupId] - Explicit subgroup to attribute the send (and its inbound reply) to.
416
- * P2P has no dedicated sender number, so pass this to record the send against a specific subgroup; it also
417
- * resolves the group. Defaults to the group's oldest subgroup.
418
- * @param {boolean} [params.useSignalHouseShortlinks] - When false, SignalHouse applies no link-shortening
419
- * or text-spin and your pre-spun links/content are sent verbatim (bring-your-own spinner). Defaults to
420
- * true server-side (the SignalHouse shortlink system, which mints unique per-recipient links).
421
- * @param {RequestOptions} [params.options] - Additional options for the request
422
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the response data from the server
423
- */
424
- async sendP2P({ recipientPhoneNumbers, messageBody, statusCallbackUrl, groupId, subgroupId, useSignalHouseShortlinks, options = {} }) {
425
- this.client._require({ recipientPhoneNumbers, messageBody });
426
- const body = { recipientPhoneNumber: recipientPhoneNumbers, messageBody };
427
- if (statusCallbackUrl) body.statusCallbackUrl = statusCallbackUrl;
428
- if (groupId) body.groupId = groupId;
429
- if (subgroupId) body.subgroupId = subgroupId;
430
- if (typeof useSignalHouseShortlinks === "boolean") body.useSignalHouseShortlinks = useSignalHouseShortlinks;
431
- return this.client(`/message/p2p`, {
432
- method: "POST",
433
- body,
434
- ...options,
435
- });
436
- }
437
-
438
- /**
439
- * Get the details of a P2P batch by its ID
440
- * @async
441
- * @roles api, admin, developer, billing, user
442
- * @param {Object} params - The parameters for getting a P2P batch
443
- * @param {string} params.batchId - The ID of the P2P batch to retrieve
444
- * @param {RequestOptions} [params.options] - Additional options for the request
445
- * @throws {Error} Throws an error if the batchId parameter is missing
446
- * @returns {Promise<SdkResponse<any>>} - The P2P batch object returned from the server
447
- */
448
- async getP2PBatch({ batchId, options = {} }) {
449
- this.client._require({ batchId });
450
- const safeBatchId = encodeURIComponent(batchId);
451
- return this.client(`/message/p2p/batches/${safeBatchId}`, { method: "GET", ...options });
452
- }
453
-
454
- /**
455
- * Send an MMS message to one or more recipient phone numbers, with optional media attachments and status callback
456
- *
457
- * The response reports the send outcome with three fields so callers do not have to inspect
458
- * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
459
- * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
460
- * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
461
- * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
462
- * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
463
- * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
464
- * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
465
- * failures with no assigned code) that is also included on the FAILED status-callback payload.
466
- * @async
467
- * @roles api, admin, developer, billing, user
468
- * @param {Object} params - The parameters for sending an MMS message
469
- * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from
470
- * @param {string[]} params.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
471
- * @param {string} params.messageBody - The body of the MMS message
472
- * @param {string[]} [params.mediaUrls] - The URLs of the media attachments
473
- * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
474
- * @param {boolean} [params.enableShortlink=false] - Whether to enable shortlink in the message
475
- * @param {boolean} [params.enableCompression=true] - Whether to enable image compression for the image attachments
476
- * @param {boolean} [params.filterLandlinesAndInactiveNumbers=false] - Whether to filter out landline and inactive numbers before sending
477
- * @param {File[]} [params.images] - The images to attach to the MMS message
478
- * @param {RequestOptions} [params.options] - Additional options for the request
479
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the response data from the server
480
- */
481
- async sendMMS({
482
- senderPhoneNumber,
483
- recipientPhoneNumbers,
484
- messageBody,
485
- mediaUrls,
486
- statusCallbackUrl,
487
- enableShortlink = false,
488
- enableCompression = true,
489
- filterLandlinesAndInactiveNumbers = false,
490
- images,
491
- options = {},
492
- }) {
493
- this.client._require({ senderPhoneNumber, recipientPhoneNumbers });
494
-
495
- const formData = new FormData();
496
-
497
- if (images && images.length > 0) {
498
- images.forEach((image, index) => {
499
- formData.append("images", image);
500
- });
501
- }
502
-
503
- formData.append("senderPhoneNumber", senderPhoneNumber);
504
-
505
- formData.append("recipientPhoneNumber", Array.isArray(recipientPhoneNumbers) ? JSON.stringify(recipientPhoneNumbers) : recipientPhoneNumbers);
506
- if (messageBody) formData.append("messageBody", messageBody);
507
-
508
- if (mediaUrls && mediaUrls.length > 0) {
509
- formData.append("mediaUrls", JSON.stringify(mediaUrls));
510
- }
511
-
512
- if (statusCallbackUrl) {
513
- formData.append("statusCallbackUrl", statusCallbackUrl);
514
- }
515
-
516
- formData.append("enableShortlink", String(enableShortlink));
517
- formData.append("enableCompression", String(enableCompression));
518
- if (filterLandlinesAndInactiveNumbers) formData.append("filterLandlinesAndInactiveNumbers", String(filterLandlinesAndInactiveNumbers));
519
-
520
- return this.multipartClient(`/message/mms`, { method: "POST", body: formData, ...options });
521
- }
522
-
523
- /**
524
- * Send a group MMS message to one or more recipient phone numbers, with optional media attachments and status callback
525
- *
526
- * The response reports the send outcome with three fields so callers do not have to inspect
527
- * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
528
- * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
529
- * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
530
- * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
531
- * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
532
- * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
533
- * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
534
- * failures with no assigned code) that is also included on the FAILED status-callback payload.
535
- * @async
536
- * @roles api, admin, developer, billing, user
537
- * @param {Object} params - The parameters for sending an MMS message
538
- * @param {string} params.senderPhoneNumber - The phone number to send the message from
539
- * @param {string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
540
- * @param {string} params.messageBody - The body of the MMS message
541
- * @param {string[]} [params.mediaUrls] - The URLs of the media attachments
542
- * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
543
- * @param {boolean} [params.enableShortlink=false] - Whether to enable shortlink in the message
544
- * @param {boolean} [params.enableCompression=true] - Whether to enable image compression for the image attachments
545
- * @param {boolean} [params.filterLandlinesAndInactiveNumbers=false] - Whether to filter out landline and inactive numbers before sending
546
- * @param {File[]} [params.images] - The images to attach to the MMS message
547
- * @param {RequestOptions} [params.options] - Additional options for the request
548
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the response data from the server
549
- */
550
- async sendGroupMessage({
551
- senderPhoneNumber,
552
- recipientPhoneNumbers,
553
- messageBody,
554
- mediaUrls,
555
- statusCallbackUrl,
556
- enableShortlink = false,
557
- enableCompression = true,
558
- filterLandlinesAndInactiveNumbers = false,
559
- images,
560
- options = {},
561
- }) {
562
- this.client._require({ senderPhoneNumber, recipientPhoneNumbers });
563
-
564
- const formData = new FormData();
565
-
566
- if (images && images.length > 0) {
567
- images.forEach((image, index) => {
568
- formData.append("images", image);
569
- });
570
- }
571
-
572
- formData.append("senderPhoneNumber", senderPhoneNumber);
573
-
574
- formData.append("recipientPhoneNumber", Array.isArray(recipientPhoneNumbers) ? JSON.stringify(recipientPhoneNumbers) : recipientPhoneNumbers);
575
- if (messageBody) formData.append("messageBody", messageBody);
576
-
577
- if (mediaUrls && mediaUrls.length > 0) {
578
- formData.append("mediaUrls", JSON.stringify(mediaUrls));
579
- }
580
-
581
- if (statusCallbackUrl) {
582
- formData.append("statusCallbackUrl", statusCallbackUrl);
583
- }
584
-
585
- formData.append("enableShortlink", String(enableShortlink));
586
- formData.append("enableCompression", String(enableCompression));
587
- if (filterLandlinesAndInactiveNumbers) formData.append("filterLandlinesAndInactiveNumbers", String(filterLandlinesAndInactiveNumbers));
588
-
589
- return this.multipartClient(`/message/groupMessage`, { method: "POST", body: formData, ...options });
590
- }
591
-
592
- /**
593
- * Look up the carrier for a phone number. Always performs a fresh lookup (not cached). Billed per request.
594
- * @async
595
- * @roles api, admin, developer, billing, user
596
- * @param {Object} params - The parameters for looking up a carrier
597
- * @param {string} params.phoneNumber - The phone number to look up (10+ digits, no + prefix)
598
- * @param {RequestOptions} [params.options] - Additional options for the request
599
- * @returns {Promise<SdkResponse<any>>} - A promise that resolves to carrier information
600
- */
601
- async carrierIdLookup({ phoneNumber, options = {} }) {
602
- this.client._require({ phoneNumber });
603
- return this.client(`/message/carrier-id`, {
604
- method: "POST",
605
- body: { phoneNumber },
606
- ...options,
607
- });
608
- }
609
- }