@raylongsolutions/saaselixir 0.0.0-stage → 1.0.1
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/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +222 -2
- package/dist/cjs/client.d.ts +184 -0
- package/dist/cjs/client.js +356 -0
- package/dist/cjs/errors.d.ts +28 -0
- package/dist/cjs/errors.js +41 -0
- package/dist/cjs/index.d.ts +6 -0
- package/dist/cjs/index.js +16 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/types.d.ts +382 -0
- package/dist/cjs/types.js +2 -0
- package/dist/cjs/values.d.ts +5 -0
- package/dist/cjs/values.js +9 -0
- package/dist/cjs/webhooks.d.ts +12 -0
- package/dist/cjs/webhooks.js +37 -0
- package/dist/esm/client.d.ts +184 -0
- package/dist/esm/client.js +352 -0
- package/dist/esm/errors.d.ts +28 -0
- package/dist/esm/errors.js +36 -0
- package/dist/esm/index.d.ts +6 -0
- package/dist/esm/index.js +4 -0
- package/dist/esm/types.d.ts +382 -0
- package/dist/esm/types.js +1 -0
- package/dist/esm/values.d.ts +5 -0
- package/dist/esm/values.js +4 -0
- package/dist/esm/webhooks.d.ts +12 -0
- package/dist/esm/webhooks.js +32 -0
- package/openapi.yaml +360 -0
- package/package.json +62 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.1
|
|
4
|
+
|
|
5
|
+
- README: noted that voice notes and photos cannot be downloaded through the SDK; a reply carries only the file id.
|
|
6
|
+
|
|
7
|
+
## 1.0.0
|
|
8
|
+
|
|
9
|
+
- Send template and text messages, safe to repeat by reference.
|
|
10
|
+
- Send to a list with `sendMany`: pace control, per-person results, early stop, resumable by reference prefix.
|
|
11
|
+
- API campaigns, chatbots and automations: create, edit, publish, list.
|
|
12
|
+
- Templates, number balance and message status lookups.
|
|
13
|
+
- Contacts (add, find, list, tags) and opt-outs.
|
|
14
|
+
- Saved lists of people and campaigns to them: preview, create, send, schedule, pause, cancel, per-person results, and `sendNow` with a cost cap.
|
|
15
|
+
- Customer replies by callback: the `message.received` event, typed.
|
|
16
|
+
- Delivery callback checking: `verifySignature` and `constructEvent`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Raylong Solutions
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,223 @@
|
|
|
1
|
-
#
|
|
1
|
+
# SaasElixir for Node.js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Send WhatsApp template messages, build chatbots and automations by describing them, and check delivery callbacks, from your own software.
|
|
4
|
+
|
|
5
|
+
- No dependencies. Node 18 or newer. Works with `import` and `require`. Typed.
|
|
6
|
+
- Sending is **safe to repeat**: every message carries a reference, and the same reference is never sent twice.
|
|
7
|
+
- Sending to a whole list is built in: steady pace, a result for each person, and it stops by itself when nothing more can go through.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @raylongsolutions/saaselixir
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Send your first message
|
|
16
|
+
|
|
17
|
+
Make a key on the **API** page of your SaasElixir account (it starts with `sxe_`) and keep it on your server.
|
|
18
|
+
|
|
19
|
+
```js
|
|
20
|
+
import { SaasElixir } from '@raylongsolutions/saaselixir';
|
|
21
|
+
|
|
22
|
+
const wa = new SaasElixir({ apiKey: process.env.SAASELIXIR_KEY });
|
|
23
|
+
|
|
24
|
+
const sent = await wa.messages.send({
|
|
25
|
+
to: '919876543210', // number with country code
|
|
26
|
+
template: 'order_confirmed', // an approved template on your number
|
|
27
|
+
language: 'en',
|
|
28
|
+
values: ['Lakshmi', 'KT-1042'], // fills {{1}}, {{2}}
|
|
29
|
+
reference: 'order-1042', // your own id; sending it again does nothing
|
|
30
|
+
});
|
|
31
|
+
// { messageId: 88213, status: 'queued', reference: 'order-1042', repeated: false }
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Words instead of a template work only for someone who wrote to you in the last 24 hours:
|
|
35
|
+
|
|
36
|
+
```js
|
|
37
|
+
await wa.messages.sendText('919876543210', 'Your order is on its way.');
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Check before and after
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
const numbers = await wa.balance.get(); // [{ channelId, number, balance, canSend }]
|
|
44
|
+
if (!numbers[0].canSend) throw new Error('Top up the number first');
|
|
45
|
+
|
|
46
|
+
const { templates } = await wa.templates.list({ status: 'APPROVED' }); // name, language, bodyVars, header needs
|
|
47
|
+
|
|
48
|
+
const info = await wa.messages.getByReference('order-1042'); // or wa.messages.get(messageId)
|
|
49
|
+
// { status: 'delivered', deliveredAt, readAt, error? } status: sending, accepted, delivered, read or failed
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Keep your contacts in step
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
// Add a person, or find the one already there. Safe to repeat; the tags are added either way.
|
|
56
|
+
const c = await wa.contacts.add({ phone: '+91 98765 43210', name: 'Lakshmi', tags: ['Wholesale'] });
|
|
57
|
+
console.log(c.contactId, c.existing, c.optedOut);
|
|
58
|
+
|
|
59
|
+
const found = await wa.contacts.findByPhone('9876543210').catch((e) => (e.code === 'no_contact' ? null : Promise.reject(e)));
|
|
60
|
+
await wa.contacts.addTags(c.contactId, ['Diwali']);
|
|
61
|
+
for await (const person of wa.contacts.each({ tag: 'Wholesale' })) console.log(person.name); // every page, one by one
|
|
62
|
+
|
|
63
|
+
await wa.optouts.add('919876543210'); // they asked to stop: every send to them is refused from now on
|
|
64
|
+
const { optedOut } = await wa.optouts.check('919876543210');
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
There is no delete, and an opt-out cannot be undone through the API: those are done on the screens, by a person.
|
|
68
|
+
|
|
69
|
+
## Send to a list
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
const people = orders.map((o) => ({ to: o.phone, template: 'diwali_offer', values: [o.name] }));
|
|
73
|
+
|
|
74
|
+
const run = await wa.messages.sendMany(people, {
|
|
75
|
+
referencePrefix: 'diwali-2026', // run it again after a crash and nobody is sent twice
|
|
76
|
+
concurrency: 5, // how many go out at once (up to 20)
|
|
77
|
+
onProgress: (person, n) => console.log(`${n.finished}/${n.total}`, person.to, person.outcome),
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
console.log(run.sent, run.failed, run.skipped);
|
|
81
|
+
if (run.stoppedBecause) console.log('Stopped early:', run.stoppedBecause); // e.g. "no_balance"
|
|
82
|
+
for (const p of run.items.filter((i) => i.outcome === 'failed')) console.log(p.to, p.error.code, p.error.message);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
| Option | What it does |
|
|
86
|
+
|---|---|
|
|
87
|
+
| `concurrency` | How many are sent at once. Default 5, up to 20. |
|
|
88
|
+
| `referencePrefix` | Makes each person's reference `<prefix>-<position>`, so a re-run is harmless. |
|
|
89
|
+
| `dedupe` | Sends once to a number listed twice. Default on. |
|
|
90
|
+
| `stopOnError` | Stop at the first failure. Default off: one bad number does not stop the rest. |
|
|
91
|
+
| `onProgress` | Called after each person. |
|
|
92
|
+
|
|
93
|
+
The run stops by itself, and marks the rest `skipped`, when every remaining message would fail the same way: `no_balance`, `plan_expired`, `plan_feature`, `unauthorized`, `paused`, `no_campaign`, `no_number`. Top up, then run the same list again with the same `referencePrefix`.
|
|
94
|
+
|
|
95
|
+
Under an API campaign (made on the API page, so you can see and pause it there): `wa.campaigns.send('order-updates', message)` and `wa.campaigns.sendMany('order-updates', people, options)`.
|
|
96
|
+
|
|
97
|
+
## Campaigns to a saved list
|
|
98
|
+
|
|
99
|
+
The same campaigns the Campaigns page makes, with the same rules: opt-outs are left out, the daily limit and your wallet are checked, and sending needs the number of people confirmed.
|
|
100
|
+
|
|
101
|
+
```js
|
|
102
|
+
import { SaasElixir, field } from '@raylongsolutions/saaselixir';
|
|
103
|
+
|
|
104
|
+
// 1. Save the people. Any size. You confirm they agreed to hear from you (WhatsApp's rule).
|
|
105
|
+
const list = await wa.audiences.create({
|
|
106
|
+
name: 'Diwali buyers',
|
|
107
|
+
consent: true,
|
|
108
|
+
members: buyers.map((b) => ({ phone: b.phone, name: b.name, fields: { plan: b.plan, city: b.city } })),
|
|
109
|
+
});
|
|
110
|
+
console.log(list.members, 'saved,', list.rejected.length, 'were not phone numbers');
|
|
111
|
+
|
|
112
|
+
// 2. Say what goes in each blank of the template: a detail of each person, or the same words for everyone.
|
|
113
|
+
const campaign = {
|
|
114
|
+
title: 'Diwali offer',
|
|
115
|
+
template: 'diwali_offer',
|
|
116
|
+
audienceId: list.id,
|
|
117
|
+
body: [field('first_name', 'there'), field('plan', 'Silver')], // {{1}}, {{2}}
|
|
118
|
+
trackClicks: true,
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
// 3. Look before you send: who is left out, what it costs, how it reads.
|
|
122
|
+
const p = await wa.broadcasts.preview(campaign);
|
|
123
|
+
console.log(p.counts, p.cost.total, p.wallet, p.samples[0].rendered, p.problems);
|
|
124
|
+
|
|
125
|
+
// 4. Send now. This stops before sending if there is a problem, the number cannot pay, or it costs more than maxCost.
|
|
126
|
+
const sent = await wa.broadcasts.sendNow(campaign, { maxCost: 5000 });
|
|
127
|
+
// or step by step: create() -> send(id, recipients), or schedule(id, new Date('2026-11-20T10:00:00+05:30'), recipients)
|
|
128
|
+
|
|
129
|
+
// 5. See how it went, and follow up the ones it failed for.
|
|
130
|
+
const now = await wa.broadcasts.get(sent.id); // status, sent, delivered, read, failed
|
|
131
|
+
for await (const person of wa.broadcasts.eachRecipient(sent.id, { state: 'failed' })) console.log(person.phone, person.error);
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`wa.broadcasts.pause(id)`, `resume(id)` and `cancel(id)` work while it sends. A campaign is sent once; if a send times out, look at `get(id)` before trying again. Named "broadcasts" here because "campaigns" in this API already means a label for single messages (`wa.campaigns.send`).
|
|
135
|
+
|
|
136
|
+
## Know when it was delivered or read
|
|
137
|
+
|
|
138
|
+
Save your address and signing secret on the API page. SaasElixir calls it when a message is sent, delivered, read or failed. Check the call is genuine before you trust it. Use the **raw** body:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import express from 'express';
|
|
142
|
+
import { constructEvent, SIGNATURE_HEADER } from '@raylongsolutions/saaselixir';
|
|
143
|
+
|
|
144
|
+
app.post('/whatsapp/status', express.raw({ type: 'application/json' }), (req, res) => {
|
|
145
|
+
let event;
|
|
146
|
+
try { event = constructEvent(process.env.SAASELIXIR_WEBHOOK_SECRET, req.body, req.headers[SIGNATURE_HEADER]); }
|
|
147
|
+
catch { return res.sendStatus(400); }
|
|
148
|
+
if (event.event === 'message.read') markRead(event.reference);
|
|
149
|
+
if (event.event === 'message.failed') alertTeam(event.reference, event.error);
|
|
150
|
+
res.sendStatus(200); // anything but 2xx is tried again over about a day
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Know when a customer writes back
|
|
155
|
+
|
|
156
|
+
Switch on **customer replies** beside your address on the API page, and each message a customer sends you is delivered to the same address, signed the same way:
|
|
157
|
+
|
|
158
|
+
```js
|
|
159
|
+
if (event.event === 'message.received') {
|
|
160
|
+
console.log(event.from, event.name, event.text); // who wrote, and what they said
|
|
161
|
+
if (event.replyToReference) markAnswered(event.replyToReference); // they answered a message you sent with this reference
|
|
162
|
+
if (event.button) handleChoice(event.button.id); // they tapped a reply button
|
|
163
|
+
if (event.mediaId) /* a photo or file: WhatsApp's id of it */;
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Reply with `wa.messages.sendText(event.from, 'Thanks!')` within 24 hours, or send a template. Replies are delivered only while your plan includes the API. Repeats carry the same `wamid`.
|
|
168
|
+
|
|
169
|
+
**Limit:** the SDK cannot download voice notes or photos. A reply gives only the file id (`event.mediaId`), so the file itself has to be fetched from WhatsApp with the number's access token. Keep that token saved on your server.
|
|
170
|
+
|
|
171
|
+
`verifySignature(secret, rawBody, signature)` gives true or false if you prefer. Calls can arrive more than once: use `reference` to ignore repeats.
|
|
172
|
+
|
|
173
|
+
## Build a chatbot or automation
|
|
174
|
+
|
|
175
|
+
```js
|
|
176
|
+
const bot = await wa.chatbots.create({ description: 'Answer questions about my shop hours and take callback requests', publish: true });
|
|
177
|
+
console.log(bot.summary, bot.todo, `charged ₹${bot.charged}`);
|
|
178
|
+
|
|
179
|
+
await wa.chatbots.edit(bot.id, { instruction: 'Also ask for the customer\'s city' });
|
|
180
|
+
await wa.chatbots.publish(bot.id); // throws with error.problems when something is unfinished
|
|
181
|
+
|
|
182
|
+
await wa.automations.create({ description: 'When an order is confirmed, send the order_confirmed template', channelId: 'your-number-id' });
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Each build is charged to your AI wallet, so the SDK never repeats one by itself.
|
|
186
|
+
|
|
187
|
+
## Errors
|
|
188
|
+
|
|
189
|
+
Every failure is a `SaasElixirError` with `code`, `message`, `httpStatus` and, for a refused publish, `problems`.
|
|
190
|
+
|
|
191
|
+
```js
|
|
192
|
+
try { await wa.messages.send(msg); }
|
|
193
|
+
catch (e) {
|
|
194
|
+
if (e.code === 'no_balance') alert('Add money to the number');
|
|
195
|
+
else if (e.code === 'opted_out') skip(msg.to);
|
|
196
|
+
else if (e.code === 'timeout') { /* safe to send again with the same reference */ }
|
|
197
|
+
else throw e;
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
| Code | Meaning |
|
|
202
|
+
|---|---|
|
|
203
|
+
| `unauthorized` | Key missing, wrong or revoked |
|
|
204
|
+
| `plan_expired`, `plan_feature` | The plan ended, or does not include the API |
|
|
205
|
+
| `no_balance` | The number has run out of balance |
|
|
206
|
+
| `opted_out` | This person asked not to be messaged |
|
|
207
|
+
| `template_not_found` | No approved template with that name and language on the number |
|
|
208
|
+
| `bad_number`, `bad_reference`, `bad_message` | The request is wrong; the message says how |
|
|
209
|
+
| `no_number` | The number is not on this account |
|
|
210
|
+
| `paused`, `no_campaign` | The API campaign is paused or does not exist |
|
|
211
|
+
| `timeout`, `network` | No answer came back. For a message this is safe to repeat |
|
|
212
|
+
|
|
213
|
+
## Options
|
|
214
|
+
|
|
215
|
+
`new SaasElixir({ apiKey, timeoutMs = 30000, maxRetries = 2, retryDelayMs = 500 })`. Sending and reading retry when the service is busy (429) or briefly down (502 to 504). `wa.raw('GET' | 'POST', path)` makes any other call with the same key and errors.
|
|
216
|
+
|
|
217
|
+
## Keep your key safe
|
|
218
|
+
|
|
219
|
+
Keep it on your server, for example in `.env`. Never put it in a web page, an app or a public repository. If it leaks, revoke it on the API page and make another. The client leaves the key out of `console.log`, JSON and error messages.
|
|
220
|
+
|
|
221
|
+
## More
|
|
222
|
+
|
|
223
|
+
The full API is described in [openapi.yaml](https://git.raylongsolutions.com/raylongsolutions/saaselixir-node/-/blob/main/openapi.yaml), which you can open in Postman or Insomnia. Questions: support@raylongsolutions.com. MIT licence.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import type * as T from './types.js';
|
|
2
|
+
export declare const VERSION = "1.0.0";
|
|
3
|
+
export interface SaasElixirOptions {
|
|
4
|
+
/** Your API key, from the API page of your SaasElixir account. It starts with sxe_. Keep it on your server. */
|
|
5
|
+
apiKey: string;
|
|
6
|
+
/** Stop waiting for an answer after this many milliseconds. Default 30000. */
|
|
7
|
+
timeoutMs?: number;
|
|
8
|
+
/** How many times a call is tried again when the service is busy or briefly down. Default 2; 0 turns it off. Only sending a message and reading are retried. */
|
|
9
|
+
maxRetries?: number;
|
|
10
|
+
/** First wait between tries, doubled each time. Default 500. */
|
|
11
|
+
retryDelayMs?: number;
|
|
12
|
+
/** Only for testing against another address. */
|
|
13
|
+
baseUrl?: string;
|
|
14
|
+
}
|
|
15
|
+
export declare class SaasElixir {
|
|
16
|
+
#private;
|
|
17
|
+
constructor(options: SaasElixirOptions);
|
|
18
|
+
toJSON(): {
|
|
19
|
+
baseUrl: string;
|
|
20
|
+
};
|
|
21
|
+
readonly messages: {
|
|
22
|
+
/**
|
|
23
|
+
* Send a template message, or a text for a chat that is open. Safe to call again after a timeout: every message has a
|
|
24
|
+
* reference (yours, or one the SDK makes), and the same reference is never sent twice. If you retry yourself, pass the same one.
|
|
25
|
+
*/
|
|
26
|
+
send: (message: T.SendMessage, o?: T.CallOptions) => Promise<T.SendResult>;
|
|
27
|
+
/** Where one message stands, by the `messageId` the send answered with. */
|
|
28
|
+
get: (messageId: number, o?: T.CallOptions) => Promise<T.MessageInfo>;
|
|
29
|
+
/** Where one message stands, by the `reference` you sent it with. */
|
|
30
|
+
getByReference: (reference: string, o?: T.CallOptions) => Promise<T.MessageInfo>;
|
|
31
|
+
/** Send to many people without a campaign. Same pace control, per-person results and early stop as campaigns.sendMany(). */
|
|
32
|
+
sendMany: (messages: T.SendMessage[], o?: T.BulkOptions) => Promise<T.BulkResult>;
|
|
33
|
+
/** Send words to someone whose chat is open (they wrote to you in the last 24 hours). */
|
|
34
|
+
sendText: (to: string, text: string, o?: T.CallOptions & {
|
|
35
|
+
reference?: string;
|
|
36
|
+
channelId?: string;
|
|
37
|
+
}) => Promise<T.SendResult>;
|
|
38
|
+
};
|
|
39
|
+
/** Your number's templates, to see which are approved and how many values each needs. Pass `status: 'APPROVED'` to list only those you can send. */
|
|
40
|
+
readonly templates: {
|
|
41
|
+
list: (q?: {
|
|
42
|
+
channelId?: string;
|
|
43
|
+
status?: string;
|
|
44
|
+
}, o?: T.CallOptions) => Promise<T.TemplateList>;
|
|
45
|
+
};
|
|
46
|
+
readonly balance: {
|
|
47
|
+
/** What each of your numbers holds and whether it can send. Check before a big send. */
|
|
48
|
+
get: (o?: T.CallOptions) => Promise<T.NumberBalance[]>;
|
|
49
|
+
};
|
|
50
|
+
readonly contacts: {
|
|
51
|
+
/** Add a person, or find the one already there; tags given are added either way. Safe to repeat. */
|
|
52
|
+
add: (input: T.ContactInput, o?: T.CallOptions) => Promise<T.ContactAdded>;
|
|
53
|
+
/** Find a person by phone number, in any writing. Throws code "no_contact" when there is none. */
|
|
54
|
+
findByPhone: (phone: string, o?: T.CallOptions) => Promise<T.Contact>;
|
|
55
|
+
get: (contactId: number, o?: T.CallOptions) => Promise<T.Contact>;
|
|
56
|
+
/** One page of people, optionally those with a tag. */
|
|
57
|
+
list: (q?: T.ContactQuery, o?: T.CallOptions) => Promise<T.ContactPage>;
|
|
58
|
+
/** Every person, page after page: `for await (const c of wa.contacts.each({ tag: 'VIP' })) ...` */
|
|
59
|
+
each: (q?: Omit<T.ContactQuery, "after">, o?: T.CallOptions) => AsyncGenerator<T.Contact, any, any>;
|
|
60
|
+
addTags: (contactId: number, tags: string[], o?: T.CallOptions) => Promise<T.Contact>;
|
|
61
|
+
removeTags: (contactId: number, tags: string[], o?: T.CallOptions) => Promise<T.Contact>;
|
|
62
|
+
};
|
|
63
|
+
readonly optouts: {
|
|
64
|
+
/** Record that someone does not want messages. Every send to them is refused from now on. Taking it back is done on the screens, by a person. */
|
|
65
|
+
add: (phone: string, o?: T.CallOptions) => Promise<T.OptOut>;
|
|
66
|
+
check: (phone: string, o?: T.CallOptions) => Promise<T.OptOut>;
|
|
67
|
+
};
|
|
68
|
+
readonly audiences: {
|
|
69
|
+
/**
|
|
70
|
+
* Save a list of people to send campaigns to. Any size: it is sent in pieces of 5000. Rows that are not phone numbers are not
|
|
71
|
+
* saved and come back in `rejected`, with their position in the list you gave. You must pass `consent: true`.
|
|
72
|
+
*/
|
|
73
|
+
create: (input: T.AudienceCreate, o?: T.CallOptions) => Promise<T.AudienceCreated>;
|
|
74
|
+
/** Add people to a list. Someone already there is updated, not repeated. Safe to repeat. */
|
|
75
|
+
addMembers: (id: number, members: T.MemberInput[], o: T.CallOptions & {
|
|
76
|
+
consent: true;
|
|
77
|
+
country?: string;
|
|
78
|
+
}) => Promise<T.AudienceMore>;
|
|
79
|
+
list: (o?: T.CallOptions) => Promise<T.Audience[]>;
|
|
80
|
+
get: (id: number, o?: T.CallOptions) => Promise<T.Audience>;
|
|
81
|
+
};
|
|
82
|
+
/**
|
|
83
|
+
* Campaigns sent to a saved list, the same ones the Campaigns page makes, with the same rules (opt-outs, daily limit, wallet).
|
|
84
|
+
* Called "broadcasts" because "campaigns" in this API already means a label for single messages.
|
|
85
|
+
*/
|
|
86
|
+
readonly broadcasts: {
|
|
87
|
+
/** See who would get it, what it costs and how it reads, without making anything. */
|
|
88
|
+
preview: (input: T.BroadcastInput, o?: T.CallOptions) => Promise<T.BroadcastPreview>;
|
|
89
|
+
/** Make a draft. Nothing is sent. */
|
|
90
|
+
create: (input: T.BroadcastInput, o?: T.CallOptions) => Promise<T.Broadcast>;
|
|
91
|
+
/** Send a draft. `confirmCount` is the number of people you checked (`recipients` of the draft or preview): if the list changed since, it is not sent. Not retried: if it times out, look at get(). */
|
|
92
|
+
send: (id: number, confirmCount: number, o?: T.CallOptions) => Promise<{
|
|
93
|
+
id: number;
|
|
94
|
+
status: string;
|
|
95
|
+
recipients: number;
|
|
96
|
+
}>;
|
|
97
|
+
/** Send at a later time, between a minute and 60 days from now. */
|
|
98
|
+
schedule: (id: number, at: Date | string, confirmCount: number, o?: T.CallOptions) => Promise<{
|
|
99
|
+
id: number;
|
|
100
|
+
status: string;
|
|
101
|
+
scheduledFor: string;
|
|
102
|
+
}>;
|
|
103
|
+
pause: (id: number, o?: T.CallOptions) => Promise<{
|
|
104
|
+
id: number;
|
|
105
|
+
status: string;
|
|
106
|
+
}>;
|
|
107
|
+
resume: (id: number, o?: T.CallOptions) => Promise<{
|
|
108
|
+
id: number;
|
|
109
|
+
status: string;
|
|
110
|
+
}>;
|
|
111
|
+
/** Stop for good: nobody not yet sent to will be. Messages already sent stay sent. */
|
|
112
|
+
cancel: (id: number, o?: T.CallOptions) => Promise<{
|
|
113
|
+
id: number;
|
|
114
|
+
status: string;
|
|
115
|
+
}>;
|
|
116
|
+
list: (o?: T.CallOptions) => Promise<T.Broadcast[]>;
|
|
117
|
+
/** How it is going: counts of sent, delivered, read and failed. */
|
|
118
|
+
get: (id: number, o?: T.CallOptions) => Promise<T.Broadcast>;
|
|
119
|
+
/** One page of the people and what happened to each. Filter by `state`, for example "failed" to follow them up. */
|
|
120
|
+
recipients: (id: number, q?: {
|
|
121
|
+
state?: T.RecipientState;
|
|
122
|
+
limit?: number;
|
|
123
|
+
after?: number;
|
|
124
|
+
}, o?: T.CallOptions) => Promise<T.RecipientPage>;
|
|
125
|
+
/** Every person, page after page: `for await (const p of wa.broadcasts.eachRecipient(id, { state: 'failed' })) ...` */
|
|
126
|
+
eachRecipient: (id: number, q?: {
|
|
127
|
+
state?: T.RecipientState;
|
|
128
|
+
}, o?: T.CallOptions) => AsyncGenerator<T.Recipient, any, any>;
|
|
129
|
+
/**
|
|
130
|
+
* Preview, make and send in one call, stopping before anything is sent when it cannot go well: a problem to fix (code "not_ready"),
|
|
131
|
+
* a number without enough balance ("no_balance"), or an estimate above `maxCost` ("too_costly"). Sending cannot be undone, so set `maxCost`.
|
|
132
|
+
*/
|
|
133
|
+
sendNow: (input: T.BroadcastInput, opts?: T.SendNowOptions & T.CallOptions) => Promise<{
|
|
134
|
+
status: string;
|
|
135
|
+
id: number;
|
|
136
|
+
title: string;
|
|
137
|
+
template: string;
|
|
138
|
+
recipients: number;
|
|
139
|
+
skipped: number;
|
|
140
|
+
sent: number;
|
|
141
|
+
delivered: number;
|
|
142
|
+
read: number;
|
|
143
|
+
failed: number;
|
|
144
|
+
estimatedCost: number;
|
|
145
|
+
scheduledFor: string | null;
|
|
146
|
+
createdAt: string;
|
|
147
|
+
error?: string;
|
|
148
|
+
pausedReason?: string;
|
|
149
|
+
}>;
|
|
150
|
+
};
|
|
151
|
+
readonly campaigns: {
|
|
152
|
+
/** Send under an API campaign, made on the API page. A paused campaign refuses with code "paused". */
|
|
153
|
+
send: (code: string, message: T.SendMessage, o?: T.CallOptions) => Promise<T.SendResult>;
|
|
154
|
+
/**
|
|
155
|
+
* Send under an API campaign to a whole list. Goes at a steady pace, reports each person, and stops by itself when every
|
|
156
|
+
* remaining message would fail the same way (no balance, plan ended, campaign paused, bad key). Never throws for one person's failure.
|
|
157
|
+
*/
|
|
158
|
+
sendMany: (code: string, messages: T.SendMessage[], o?: T.BulkOptions) => Promise<T.BulkResult>;
|
|
159
|
+
};
|
|
160
|
+
readonly chatbots: {
|
|
161
|
+
list: (o?: T.CallOptions) => Promise<T.Bot[]>;
|
|
162
|
+
get: (id: number, o?: T.CallOptions) => Promise<T.Bot & {
|
|
163
|
+
steps: number;
|
|
164
|
+
}>;
|
|
165
|
+
/** Describe a chatbot in words. Charged to your AI wallet; never retried by the SDK. */
|
|
166
|
+
create: (input: T.BuildInput, o?: T.CallOptions) => Promise<T.BuildResult>;
|
|
167
|
+
/** Change a chatbot in words. Charged to your AI wallet; never retried by the SDK. */
|
|
168
|
+
edit: (id: number, input: T.EditInput, o?: T.CallOptions) => Promise<T.BuildResult>;
|
|
169
|
+
/** Make the draft live. Refused with a list of problems (error.problems) when something is unfinished. */
|
|
170
|
+
publish: (id: number, o?: T.CallOptions) => Promise<T.PublishResult>;
|
|
171
|
+
};
|
|
172
|
+
readonly automations: {
|
|
173
|
+
list: (o?: T.CallOptions) => Promise<T.Bot[]>;
|
|
174
|
+
create: (input: T.AutomationInput, o?: T.CallOptions) => Promise<T.BuildResult>;
|
|
175
|
+
edit: (id: number, input: T.EditInput, o?: T.CallOptions) => Promise<T.BuildResult>;
|
|
176
|
+
publish: (id: number, o?: T.CallOptions) => Promise<T.PublishResult>;
|
|
177
|
+
};
|
|
178
|
+
/** Any other call, with the same key and error handling. Retried only when retrySafe is true. */
|
|
179
|
+
raw<R = unknown>(method: 'GET' | 'POST', path: string, p?: {
|
|
180
|
+
body?: unknown;
|
|
181
|
+
retrySafe?: boolean;
|
|
182
|
+
timeoutMs?: number;
|
|
183
|
+
}): Promise<R>;
|
|
184
|
+
}
|