\n\n# @sendly/node\n\nOfficial Node.js SDK for the [Sendly](https://sendly.live) SMS API.\n\n## Installation\n\n```bash\nnpm install @sendly/node\n# or\nyarn add @sendly/node\n# or\npnpm add @sendly/node\n```\n\n## Requirements\n\n- Node.js 18.0.0 or higher\n- A Sendly API key ([get one here](https://sendly.live/dashboard))\n\n## Quick Start\n\n```typescript\nimport Sendly from '@sendly/node';\n\n// Initialize with your API key\nconst sendly = new Sendly('sk_live_v1_your_api_key');\n\n// Send an SMS\nconst message = await sendly.messages.send({\n to: '+15125550123',\n text: 'Hello from Sendly!'\n});\n\nconsole.log(`Message sent: ${message.id}`);\nconsole.log(`Status: ${message.status}`);\n```\n\n## Prerequisites for Live Messaging\n\nBefore sending live SMS messages, you need:\n\n1. **Business Verification** - Complete verification in the [Sendly dashboard](https://sendly.live/dashboard)\n - **International**: Instant approval (just provide Sender ID)\n - **US/Canada**: Requires carrier approval\n\n2. **Credits** - Add credits to your account\n - Test keys (`sk_test_*`) work without credits (sandbox mode)\n - Live keys (`sk_live_*`) require credits for each message\n\n3. **Live API Key** - Generate after verification + credits\n - Dashboard → API Keys → Create Live Key\n\n### Test vs Live Keys\n\n| Key Type | Prefix | Credits Required | Verification Required | Use Case |\n|----------|--------|------------------|----------------------|----------|\n| Test | `sk_test_v1_*` | No | No | Development, testing |\n| Live | `sk_live_v1_*` | Yes | Yes | Production messaging |\n\n> **Note**: You can start development immediately with a test key. Messages to sandbox test numbers are free and don't require verification.\n\n## Features\n\n- ✅ Full TypeScript support with exported types\n- ✅ Automatic retries with exponential backoff on network errors, timeouts, `408` and `5xx`\n- ✅ Automatic idempotency keys on POSTs (except `sendBatch`, which the API dedupes by content), reused on every retry, so a retried send never charges twice\n- ✅ Rate limits surfaced as a typed `RateLimitError` with `retryAfter` (an ordinary\n `429` is raised at once so you decide; only the brief key-check `429` is waited out for you)\n- ✅ Promise-based async/await API\n- ✅ ESM and CommonJS support\n- ✅ Zero runtime dependencies\n\n## Usage\n\n### Sending Messages\n\n```typescript\nimport Sendly from '@sendly/node';\n\nconst sendly = new Sendly('sk_live_v1_xxx');\n\n// Basic usage (marketing message - default)\nconst message = await sendly.messages.send({\n to: '+15125550123',\n text: 'Check out our new features!'\n});\n\n// Transactional message (bypasses quiet hours)\nconst otp = await sendly.messages.send({\n to: '+15125550123',\n text: 'Your verification code is: 123456',\n messageType: 'transactional'\n});\n\n// International: sent from your verified sender ID, or from a number you own\n// for that country\nconst intl = await sendly.messages.send({\n to: '+447700900123',\n text: 'Hello from MyApp!'\n});\nconsole.log(intl.from, intl.senderType); // e.g. 'MYAPP', 'alphanumeric'\n\n// From a specific number you own. A +1 number reaches US/Canada (and other +1\n// countries); to anywhere else your sender ID is used and the response has a\n// `warning`.\nconst owned = await sendly.messages.send({\n to: '+15125550123',\n text: 'Your order has shipped!',\n from: '+15125550199'\n});\n```\n\n`from` takes a number you own. The sender ID for international sends is the\none on your verification, not a value you pass: any other `from` is ignored\nfor an international destination (the response carries a `warning` saying\nwhich sender was used) and refused with `400 invalid_from_number` for US and\nCanada.\n\n### Listing Messages\n\n```typescript\n// Get recent messages (default limit: 50, max 100)\nconst { data: messages, pagination } = await sendly.messages.list();\nconsole.log(`${messages.length} of ${pagination?.total}`);\n\n// The last 10 delivered messages\nconst { data: delivered } = await sendly.messages.list({\n status: 'delivered',\n limit: 10,\n offset: 0,\n});\n\n// Iterate through messages\nfor (const msg of delivered) {\n console.log(`${msg.to}: ${msg.status}`);\n}\n\n// Page through everything without managing offsets yourself\nfor await (const msg of sendly.messages.listAll({ status: 'failed', limit: 100 })) {\n console.log(msg.id, msg.error);\n}\n```\n\n`pagination` carries `total` (every message matching the filter), `limit`,\n`offset`, `page`, `totalPages` and `hasMore`. `count` is only the number of\nrows on this page. `listAll()` follows `hasMore` for you and applies `status`\nand `offset` to every page.\n\n### Getting a Message\n\n```typescript\nconst message = await sendly.messages.get('4a7c1e2f-9b3d-4c8a-91f2-7d5e6a0b3c19');\n\nconsole.log(`Status: ${message.status}`);\nconsole.log(`Delivered: ${message.deliveredAt}`);\n```\n\n### Scheduling Messages\n\n```typescript\n// Schedule a message for future delivery\nconst scheduled = await sendly.messages.schedule({\n to: '+15125550123',\n text: 'Your appointment is tomorrow!',\n scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString() // 5 minutes to 5 days ahead\n});\n\nconsole.log(`Scheduled: ${scheduled.id}`);\nconsole.log(`Will send at: ${scheduled.scheduledAt}`);\n\n// List scheduled messages\nconst { data: scheduledMessages } = await sendly.messages.listScheduled();\n\n// Get a specific scheduled message (scheduled ids are schd_ prefixed, sent\n// message ids are bare UUIDs — the SDK rejects anything that isn't a UUID or\n// a msg_/schd_/batch_ id before it sends)\nconst msg = await sendly.messages.getScheduled(scheduled.id);\n\n// Cancel a scheduled message (refunds credits)\nconst result = await sendly.messages.cancelScheduled(scheduled.id);\nconsole.log(`Refunded: ${result.creditsRefunded} credits`);\n```\n\n### Batch Messages\n\n```typescript\n// Preview the batch first (dry run): validates and prices without sending\nconst preview = await sendly.messages.previewBatch({\n messages: [\n { to: '+15125550123', text: 'Hello User 1!' },\n { to: '+447700900123', text: 'Hello UK!' }\n ]\n});\nconsole.log(`Sendable: ${preview.sendable} of ${preview.total}`);\nconsole.log(`Credits needed: ${preview.creditsNeeded} (balance ${preview.creditBalance})`);\nfor (const blocked of preview.blockedMessages ?? []) {\n console.log(`${blocked.to}: ${blocked.reason}`);\n}\n\n// Send multiple messages in one API call (up to 10,000)\nif (preview.canSend) {\n const batch = await sendly.messages.sendBatch({\n messages: [\n { to: '+15125550123', text: 'Hello User 1!' },\n { to: '+447700900123', text: 'Hello UK!' }\n ]\n });\n\n console.log(`Batch ID: ${batch.batchId}`);\n console.log(`Status: ${batch.status}`); // 'processing' while a live batch sends\n console.log(`Skipped: ${batch.optedOutSkipped} opted out, ${batch.invalidSkipped} invalid`);\n\n // Get the outcome: sent, delivered and failed counts, and every message\n const result = await sendly.messages.getBatch(batch.batchId);\n console.log(result.sent, result.delivered, result.failed, result.creditsReserved, result.creditsRefunded);\n}\n\n// List batches (without their messages; call getBatch for those)\nconst { data: batches } = await sendly.messages.listBatches({ status: 'completed' });\n```\n\n`canSend` is the field to check before sending. A live send skips recipients\nwho opted out, but rejects the whole batch if any other message is blocked\n(for example an unsupported destination or restricted content), so `canSend`\nis false in that case even though `sendable` is above zero. It is also false when\nthe balance does not cover `creditsNeeded` (a test key's sends are free, so\nthat check is skipped) or the key lacks the `sms:send` scope. The preview also\nreturns `byCountry`, `duplicates`, `compliance` and `warnings`.\n\nA live `sendBatch` usually answers while the batch is still `processing`, with\nan empty `messages` array; `getBatch` returns the outcome. `queued` and\n`createdAt` on the send result are deprecated (the send never returns them):\nread them from `getBatch`.\n\n### Group MMS\n\n```typescript\n// Send a group MMS to 2-8 recipients (US/Canada only). Every recipient sees\n// the others and replies fan out to the whole group. Requires an MMS-enabled,\n// 10DLC-registered number you own (omit `from` to use your default sender).\nconst group = await sendly.messages.sendGroup({\n to: ['+14155550101', '+14155550102'],\n text: 'Hey team - quick sync at noon?'\n});\n\nconsole.log(group.id); // 4a7c1e2f-9b3d-4c8a-91f2-7d5e6a0b3c19\nconsole.log(group.status); // 'sent' (or 'delivered' when simulated)\nconsole.log(group.to); // ['+14155550101', '+14155550102']\nconsole.log(group.group_message_id); // grp_xxx (present on live sends)\n\n// Live sends also list each recipient with its own delivery status\nfor (const r of group.recipients ?? []) {\n console.log(`${r.phoneNumber}: ${r.status}`);\n}\n```\n\n`to` is always the list of numbers. `recipients` is present on a live send\nonly; a simulated send (test key, or before your verification is approved)\nhas `simulated: true` and a `message` explaining why.\n\n### AI Enhance\n\n```typescript\n// Rewrite a draft into a single, polished SMS segment. Provide `text`,\n// `messageType`, or both.\nconst result = await sendly.messages.enhance({\n text: 'hey come check out our sale this weekend',\n messageType: 'marketing'\n});\n\nconsole.log(result.enhanced); // polished, <=160-char rewrite\nconsole.log(result.explanation); // what changed and why\n```\n\n### Rate Limits\n\nRequests are counted per API key in a fixed 60-second window: **60/minute**\non a test key, **600/minute** on a live key, and **3000/minute** on an\nenterprise master key.\n\n```typescript\n// After any API call, you can check rate limit status\nawait sendly.messages.send({ to: '+15125550123', text: 'Hello!' });\n\nconst rateLimit = sendly.getRateLimitInfo();\nif (rateLimit) {\n console.log(`${rateLimit.remaining}/${rateLimit.limit} requests remaining`);\n console.log(`Resets in ${rateLimit.reset} seconds`);\n}\n```\n\nGoing over the limit raises `RateLimitError` with `retryAfter` in seconds. The\nSDK does **not** wait out an ordinary `429` for you: it throws straight away so\nyou can decide whether to back off, shed load, or queue. Check `code` first,\nbecause one `429` must not be retried as it is:\n\n```typescript\ntry {\n await sendly.messages.send({ to: '+15125550123', text: 'Hello!' });\n} catch (error) {\n if (error instanceof RateLimitError) {\n if (error.code === 'too_many_failed_key_attempts') {\n // Repeated wrong API keys from this address locked it out.\n // Fix the key. Until retryAfter has passed, even the right key can be refused.\n throw error;\n }\n await new Promise((r) => setTimeout(r, error.retryAfter * 1000));\n }\n}\n```\n\nThe `RateLimitError` codes:\n\n- `rate_limit_exceeded`: the per-key request limit above. Thrown at once.\n- `too_many_failed_key_attempts`: too many requests with a wrong API key came\n from your address. Thrown at once. Retrying does not help: fix the key; until\n `retryAfter` seconds pass, a correct key can still be refused.\n- `too_many_concurrent_verifications`: too many first-time key checks were\n running at once from your address. The request never ran, so the SDK waits\n its `retryAfter` (1 second) and sends it again with the same idempotency\n key; you only see this error once `maxRetries` run out.\n\nNetwork errors, request timeouts, `408` and `5xx` responses are retried\nautomatically too (up to `maxRetries`, with exponential backoff and jitter).\nThree WhatsApp calls throw a `5xx`, a timeout or a network error at once\ninstead: `whatsapp.signup.create` with a `businessAccountId`,\n`whatsapp.signup.verify` and `whatsapp.senders.uploadProfilePhoto`, because\nrepeating them can start a new charged signup or use up a verification\nattempt. They still wait out a `429 too_many_concurrent_verifications`, which\nnever ran.\nEvery other `4xx` is a final answer and is thrown on the first attempt,\nincluding a `409` conflict, a `410` expired code and the `429\nmax_attempts_exceeded` from `verify.check`.\n\n## Configuration\n\n```typescript\nimport Sendly from '@sendly/node';\n\nconst sendly = new Sendly({\n apiKey: 'sk_live_v1_xxx',\n\n // Optional: Custom base URL (for testing)\n baseUrl: 'https://sendly.live/api/v1',\n\n // Optional: Request timeout in ms (default: 30000)\n timeout: 60000,\n\n // Optional: Max retry attempts (default: 3)\n maxRetries: 5\n});\n```\n\nThe client throws at construction time if the key is not shaped\n`sk_test_v1_…` / `sk_live_v1_…`, or if `baseUrl` is plain `http://` for\nanything other than this machine (`localhost`, `*.localhost`, `127.0.0.0/8`,\n`[::1]`).\n\n## Idempotency\n\nPOSTs carry an automatically generated `Idempotency-Key`, and the SDK sends the\nsame key on every retry of that call: after a timeout, a network error, a `408`,\na `5xx` or the key-check `429`. The exception is `sendBatch`, which sends a key\nonly when you pass `idempotencyKey`; without one, the API dedupes a retried\nbatch by its content. On the endpoints that deduplicate (sends, batch, group,\nschedule, conversation replies, draft approval, verify, number purchase, credit\ntransfers, enterprise deposits and provisioning, WhatsApp signup and template\ncreation, calls, and RCS and short-code writes), a retry of a request that\nalready reached the API returns the original result instead of sending and\ncharging again. The API never records a `5xx` or a `429` under a key, so a\nretry after one of those runs the request again; a `2xx` or any other `4xx`\nis recorded and replayed. Uploads also carry a key, but the API does not\ndeduplicate them, so a retried upload can store the file twice. You do not\nhave to do anything to get this.\n\nPass your own key when the guarantee needs to outlive the process — a job queue\nthat re-runs after a crash, or your own retry loop:\n\n```typescript\nawait sendly.messages.send(\n { to: '+15125550123', text: 'Your order has shipped!' },\n { idempotencyKey: `order-4821-shipped` }\n);\n```\n\nReusing a key within 24 hours returns the original response. Reusing it with a\ndifferent body returns `422 idempotency_key_mismatch`, so derive keys from\nsomething stable in your domain, like an order id. `sendBatch` sends no\nautomatic key, because the API already deduplicates identical batches by their\ncontents.\n\nFull details: https://sendly.live/docs/idempotency\n\n## Webhooks\n\nManage webhook endpoints to receive real-time delivery status updates.\n\n```typescript\n// Create a webhook endpoint\nconst webhook = await sendly.webhooks.create({\n url: 'https://acme.example/webhooks/sendly',\n events: ['message.delivered', 'message.failed']\n});\n\nconsole.log(`Webhook ID: ${webhook.id}`);\nconsole.log(`Secret: ${webhook.secret}`); // Only returned at creation - store securely!\n\n// List all webhooks\nconst webhooks = await sendly.webhooks.list();\n\n// Get a specific webhook\nconst wh = await sendly.webhooks.get('whk_xxx');\n\n// Update a webhook\nawait sendly.webhooks.update('whk_xxx', {\n url: 'https://new-endpoint.acme.example/webhook',\n events: ['message.delivered', 'message.failed', 'message.sent']\n});\n\n// Test a webhook (sends a test event). It resolves only when your endpoint\n// accepted the event; otherwise it throws a ValidationError (400) whose\n// message says why.\nconst testResult = await sendly.webhooks.test('whk_xxx');\nconsole.log(testResult.message, testResult.statusCode, testResult.responseTimeMs);\n\n// Rotate webhook secret. Deliveries are signed with the new secret as soon as\n// this returns, so let your endpoint accept both secrets while you deploy it.\nconst rotation = await sendly.webhooks.rotateSecret('whk_xxx');\nconsole.log(`New secret: ${rotation.secret}`, rotation.rotatedAt);\n\n// View delivery history, newest first (filter by status, page with limit/offset)\nconst deliveries = await sendly.webhooks.getDeliveries('whk_xxx', { status: 'failed', limit: 50 });\nfor (const d of deliveries) {\n console.log(d.id, d.eventType, d.httpStatus, d.errorMessage);\n}\n\n// Retry a failed delivery\nawait sendly.webhooks.retryDelivery('whk_xxx', 'del_yyy');\n\n// The event types you can subscribe to, with what each one reports\nconst eventTypes = await sendly.webhooks.listEventTypeDetails();\nconsole.log(eventTypes.map((e) => `${e.type}: ${e.description}`));\n\n// Delete a webhook\nawait sendly.webhooks.delete('whk_xxx');\n```\n\nWebhook ids are `whk_` prefixed and delivery ids `del_` prefixed; the SDK\nchecks both before sending the request, so a mistyped id throws locally rather\nthan round-tripping. `create` throws a `ValidationError` before sending when\nthe URL is missing or not `https://` or `events` is empty, and `update` does\nthe same for a URL that is not `https://`. `listEventTypes()` returns just the\nnames.\n\n### Recovering from an outage\n\nRepeated failures trip a circuit breaker and deliveries stop. Once your\nendpoint is healthy again, reset the circuit, then replay what was missed:\n\n```typescript\n// 1. Close the circuit (otherwise replay/backfill answer 409)\nawait sendly.webhooks.resetCircuit('whk_xxx');\n\n// 2. Replay deliveries we recorded but could not deliver. Each replay keeps\n// the original event_id, so your handler can dedupe on it.\nconst replay = await sendly.webhooks.redeliver('whk_xxx', {\n since: new Date(Date.now() - 6 * 24 * 60 * 60 * 1000).toISOString(), // at most 7 days back\n eventTypes: ['message.delivered', 'message.failed'],\n statuses: ['failed', 'cancelled'], // default\n limit: 5000, // default 1000, max 10000\n});\nconsole.log(replay.requeued, replay.truncated, replay.deliveryIds.length);\n\n// 3. Backfill events that never got an audit row at all. They carry the\n// event id the original dispatch would have used, so dedupe on event.id.\nconst filled = await sendly.webhooks.backfill('whk_xxx', {\n since: new Date(Date.now() - 6 * 24 * 60 * 60 * 1000).toISOString(), // at most 7 days back\n});\nconsole.log(filled.synthesized, filled.byType);\n```\n\n### Verifying Webhook Signatures\n\nEvery delivery carries `X-Sendly-Signature` (`sha256=`) and\n`X-Sendly-Timestamp`. The signed string is `.`, so you\nmust pass **both** the signature and the timestamp, and you must hand the\nverifier the **raw request body** — a body that has already been through\n`JSON.parse` and re-serialized will not match.\n\nSigning secrets are returned once, at webhook creation, and start with\n`whsec_`.\n\n```typescript\nimport { Webhooks } from '@sendly/node';\n\nconst webhooks = new Webhooks(process.env.SENDLY_WEBHOOK_SECRET!); // whsec_...\n\n// In your webhook handler (express.raw({ type: 'application/json' }))\napp.post('/webhooks/sendly', (req, res) => {\n const signature = req.headers['x-sendly-signature'] as string;\n const timestamp = req.headers['x-sendly-timestamp'] as string;\n const payload = req.body.toString('utf8'); // raw body, not parsed JSON\n\n try {\n const event = webhooks.parse(payload, signature, timestamp);\n\n switch (event.type) {\n case 'message.delivered':\n console.log(`Message ${event.data.object.id} delivered`);\n break;\n case 'message.failed':\n console.log(`Message ${event.data.object.id} failed: ${event.data.object.error}`);\n break;\n }\n\n res.status(200).send('OK');\n } catch (error) {\n console.error('Invalid signature');\n res.status(401).send('Invalid signature');\n }\n});\n```\n\nThe same thing is available as free functions, if you would rather not hold an\ninstance. Note the argument order — **payload, signature, secret, timestamp** —\nand that `timestamp` is last and optional in the signature but required in\npractice, because Sendly always signs with one:\n\n```typescript\nimport { verifyWebhookSignature, parseWebhookEvent, WebhookSignatureError } from '@sendly/node';\n\nconst ok = verifyWebhookSignature(\n payload, // raw body string\n req.headers['x-sendly-signature'] as string,\n process.env.SENDLY_WEBHOOK_SECRET!,\n req.headers['x-sendly-timestamp'] as string, // omit and verification WILL fail\n 300, // max age in seconds (default 300)\n);\n\n// Or verify and parse in one step (throws WebhookSignatureError)\nconst event = parseWebhookEvent(\n payload,\n req.headers['x-sendly-signature'] as string,\n process.env.SENDLY_WEBHOOK_SECRET!,\n req.headers['x-sendly-timestamp'] as string,\n);\n```\n\nThe statics `Webhooks.verifySignature(payload, signature, secret)` and\n`Webhooks.parseEvent(...)` are deprecated. They take no timestamp, so they\ncannot verify a real Sendly delivery, and are kept only for older code that\nsigns payloads itself. Use the instance methods or the free functions above.\n\nThe events a webhook may subscribe to are the members of the `WebhookEventType`\nunion, except two retired values, `message.queued` and `message.undelivered`:\nthe API never emits them and rejects them in a subscription.\n\n### Lifecycle Events\n\n`WebhookEvent.data.object` is typed as a message, which is right for `message.*` and\nwrong for everything else. Lifecycle events — `rcs_*`, `whatsapp_*`, `call.*`,\n`brand.*`, `campaign.*`, `assignment.*`, `number.*`, `port*` and `contact.*` — carry a\ndifferent object entirely, so the message fields you reach for are `undefined` at\nruntime. Read those with `webhookObject(event)`, which hands you `data.object` as\nthe shape you declare.\n\n```typescript\nimport { Webhooks, webhookObject, type WebhookEvent } from '@sendly/node';\n\nconst webhooks = new Webhooks(process.env.SENDLY_WEBHOOK_SECRET!);\n\ninterface RcsAgentObject {\n agent_id: string;\n name: string;\n stage: string;\n}\n\ninterface NumberObject {\n id: string;\n phone: string;\n status: string;\n country_code: string | null;\n}\n\napp.post('/webhooks/sendly', (req, res) => {\n let event: WebhookEvent;\n try {\n event = webhooks.parse(\n req.body, // raw body string, not parsed JSON\n req.headers['x-sendly-signature'] as string,\n req.headers['x-sendly-timestamp'] as string\n );\n } catch {\n return res.status(401).send('Invalid signature');\n }\n\n switch (event.type) {\n case 'message.delivered':\n // message.* events: data.object really is a message\n console.log(`Message ${event.data.object.id} delivered`);\n break;\n\n case 'rcs_agent.live': {\n const agent = webhookObject(event);\n console.log(`RCS agent ${agent.agent_id} (${agent.name}) is ${agent.stage}`);\n break;\n }\n\n case 'number.activated': {\n const number = webhookObject(event);\n console.log(`${number.phone} activated (${number.id})`);\n break;\n }\n }\n\n res.status(200).send('OK');\n});\n```\n\n`webhookObject` is a cast, not a validator: it returns `data.object` under the type you\nname and does not check the payload against it. Note also that `data.object.id` is the\nid of whatever the event is about — a contact id on `contact.auto_flagged`, a\nphone-number id on `number.activated`. Only treat it as a message id on `message.*`.\n\n## Account & Credits\n\n```typescript\n// Get account information, plus the key's workspace, verification and limits\nconst account = await sendly.account.get();\nconsole.log(`Email: ${account.email}`);\nconsole.log(account.organization?.name, account.verification?.status);\nconsole.log(account.apiKey?.type, account.apiKey?.scopes);\n\n// Check credit balance\nconst credits = await sendly.account.getCredits();\nconsole.log(`Available: ${credits.availableBalance} credits`);\nconsole.log(`Reserved (scheduled): ${credits.reservedBalance} credits`);\nconsole.log(`Total: ${credits.balance} credits`);\n\n// View credit transaction history, newest first\nconst transactions = await sendly.account.getCreditTransactions({ limit: 20 });\nfor (const tx of transactions) {\n console.log(`${tx.type}: ${tx.amount} credits (balance ${tx.balanceAfter}) - ${tx.description}`);\n}\n\n// Only one type of transaction\nconst refunds = await sendly.account.getCreditTransactions({ type: 'refund' });\n\n// List API keys\nconst keys = await sendly.account.listApiKeys();\nfor (const key of keys) {\n console.log(`${key.name}: ${key.prefix}*** (${key.type})`);\n}\n\n// Get API key usage stats\nconst usage = await sendly.account.getApiKeyUsage('key_xxx');\nconsole.log(`Requests: ${usage.summary.totalRequests}`);\nconsole.log(`Credits used: ${usage.summary.totalCredits}`);\n\n// Create a new API key: a test key unless you pass type 'live'. A live key\n// needs a verified business (403 verification_required) and a credit balance\n// (402 credits_required). A key can grant only scopes it holds itself; leave\n// out scopes and the new key gets the calling key's.\nconst { apiKey, key } = await sendly.account.createApiKey('Production Key', {\n type: 'live',\n scopes: ['sms:send', 'sms:read'],\n expiresAt: '2027-01-01T00:00:00Z',\n});\nconsole.log(`New key: ${key}`); // Only shown once!\nconsole.log(`Key ID: ${apiKey.id}`, apiKey.permissions, apiKey.expiresAt);\n\n// Rename an API key\nawait sendly.account.renameApiKey('key_xxx', 'Production Key');\n\n// Revoke an API key\nawait sendly.account.revokeApiKey('key_xxx');\n\n// Move credits to another workspace you control\nawait sendly.account.transferCredits({\n targetOrganizationId: '9b2f4c1e-7d3a-4e5b-8c6f-0a1b2c3d4e5f', // workspace id\n amount: 5000,\n});\n\n// Rotate an API key — issues a new key and keeps the old one working for a\n// grace period (gracePeriodHours: 24-168, default 24) so you can roll callers\n// over without downtime. The new secret is shown only once.\nconst { newKey, oldKey, message } = await sendly.account.rotateApiKey('key_xxx', {\n gracePeriodHours: 72\n});\nconsole.log(`New key: ${newKey.key}`); // Save this - shown once!\nconsole.log(message); // \"Old key will expire in 72 hours\"\n```\n\n## Verify (OTP)\n\nSend a one-time code, check it, and read the verification back. Sandbox keys\nreturn the code on the response so you can test without a handset.\n\n```typescript\n// Send a code\nconst verification = await sendly.verify.send({\n to: '+15125550123',\n appName: 'MyApp',\n codeLength: 6, // 4-10, default 6\n timeoutSecs: 300, // 60-3600, default 300\n});\nconsole.log(verification.id, verification.expiresAt);\nif (verification.sandboxCode) console.log('Test code:', verification.sandboxCode);\n\n// Check what the user typed. Only a correct code resolves; a wrong, expired or\n// used-up code throws, and none of these is retried by the SDK\ntry {\n const result = await sendly.verify.check(verification.id, { code: '123456' });\n console.log('Phone verified at', result.verifiedAt);\n} catch (error) {\n if (error instanceof SendlyError && error.code === 'invalid_code') {\n // 400, a ValidationError\n console.log(`${error.response?.remaining_attempts} attempts left`);\n } else if (error instanceof SendlyError && error.code === 'expired') {\n console.log('Code expired (410): send a new one');\n } else if (error instanceof SendlyError && error.code === 'max_attempts_exceeded') {\n console.log('Too many wrong codes (429): send a new one');\n } else {\n throw error;\n }\n}\n\n// Resend, fetch, and list\nawait sendly.verify.resend(verification.id);\nconst record = await sendly.verify.get(verification.id);\nconsole.log(record.deliveryStatus, record.attempts, record.maxAttempts);\n\nconst { verifications, pagination } = await sendly.verify.list({ limit: 10 });\nconst verified = verifications.filter((v) => v.status === 'verified');\nconsole.log(verified.length, pagination.hasMore);\n```\n\n### Hosted verification sessions\n\nHand the phone-number-and-code UI to Sendly: create a session, send the user to\n`url`, then validate the token you get back on your success URL.\n\n```typescript\nconst session = await sendly.verify.sessions.create({\n successUrl: 'https://acme.example/verified',\n cancelUrl: 'https://acme.example/cancelled',\n brandName: 'Acme',\n brandColor: '#0B6E4F',\n metadata: { userId: 'u_123' },\n});\nconsole.log(session.url, session.expiresAt);\n\n// On your success URL, validate the token\nconst check = await sendly.verify.sessions.validate({ token: 'tok_from_query' });\nif (check.valid) console.log(check.phone, check.verifiedAt, check.metadata);\n```\n\n## Templates\n\nReusable message bodies with `{{variables}}`. Presets ship with the account;\nyour own start as drafts and must be published before the Verify API can use\nthem.\n\n```typescript\n// Presets and your own templates\nconst { templates: presets } = await sendly.templates.presets();\nconst { templates } = await sendly.templates.list();\n\n// Create, preview, publish\nconst template = await sendly.templates.create({\n name: 'My OTP',\n text: 'Your {{app_name}} code is {{code}}',\n});\nconst preview = await sendly.templates.preview(template.id, {\n app_name: 'MyApp',\n code: '123456',\n});\nconsole.log(preview.previewText); // \"Your MyApp code is 123456\"\nconsole.log(preview.characterCount, preview.segmentCount); // 25, 1\nconst published = await sendly.templates.publish(template.id);\nconsole.log(published.status); // 'published'\n\n// Clone a preset to customise it, update, delete\nconst mine = await sendly.templates.clone('tpl_preset_otp', { name: 'My Custom OTP' });\nawait sendly.templates.update(mine.id, { text: 'Your {{app_name}} code: {{code}}' });\nawait sendly.templates.delete(mine.id);\n\n// Draft one with AI from a description\nconst generated = await sendly.templates.generate({\n description: 'Appointment reminder for a dental clinic',\n});\nconsole.log(generated.text, generated.variables);\n```\n\n## Campaigns\n\nBulk sends to a contact list, with a cost preview before you commit.\n\n```typescript\nconst campaign = await sendly.campaigns.create({\n name: 'Welcome Campaign',\n text: 'Hi {{name}}! Thanks for joining {{brand_name}}.',\n contactListIds: ['lst_xxx'], // one list per campaign\n});\n\n// What it will cost, and whether you can afford it\nconst preview = await sendly.campaigns.preview(campaign.id);\nconsole.log(preview.recipientCount, preview.estimatedCredits, preview.hasEnoughCredits);\nconsole.log(`Skipped: ${preview.optedOutCount} opted out, ${preview.landlineCount} landlines`);\n\n// Send now...\nconst sent = await sendly.campaigns.send(campaign.id);\nconsole.log(`Sent ${sent.sentCount} of ${sent.recipientCount} in batch ${sent.batchId}`);\nconst outcome = await sendly.messages.getBatch(sent.batchId); // delivery results\n\n// ...or schedule a draft in a timezone\nconst draft = await sendly.campaigns.clone(campaign.id);\nawait sendly.campaigns.schedule(draft.id, {\n scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),\n timezone: 'America/New_York',\n});\n\n// Follow it, cancel a scheduled one\nconst current = await sendly.campaigns.get(draft.id);\nconsole.log(current.status); // 'scheduled'\nawait sendly.campaigns.cancel(draft.id);\n\n// List with paging\nconst { campaigns, total } = await sendly.campaigns.list({ status: 'completed', limit: 10 });\n```\n\nA campaign fills two placeholders when it sends: `{{name}}` (the contact's\nname) and `{{brand_name}}` (your brand name). Any other placeholder in `text`\nreaches recipients as typed, and a template that uses one is refused. A\ncampaign targets one list, so passing more than one id in `contactListIds`\nthrows a `ValidationError` before any request is made.\n\n`send()` resolves to a `CampaignSendResult`: the batch the messages went out\nin, with `batchId`, `status`, `recipientCount`, `sentCount`, `failedCount`,\n`creditsUsed`, `creditsRefunded`, `optedOutSkipped` and `invalidSkipped`. Call\n`campaigns.get(id)` for the campaign itself. A sent campaign's status is\n`completed`; `sent` and `paused` are in `CampaignStatus` but never returned.\n\n## Contacts & Lists\n\n```typescript\n// Contacts\nconst contact = await sendly.contacts.create({\n phoneNumber: '+15125550123',\n name: 'Jordan Reed',\n email: 'jordan@acme.example',\n metadata: { plan: 'pro' },\n});\nconst { contacts, total } = await sendly.contacts.list({ search: 'jordan', limit: 50 });\nawait sendly.contacts.update(contact.id, { name: 'Jordan R.' });\nawait sendly.contacts.delete(contact.id);\n\n// Bulk import\nconst imported = await sendly.contacts.import({\n contacts: [\n { phone: '+15125550123', name: 'Sam', optedInAt: '2026-05-01T12:00:00Z' },\n { phone: '+15125550124', name: 'Alex' },\n ],\n listId: 'lst_xxx',\n});\nconsole.log(imported.imported, imported.skippedDuplicates, imported.errors);\n\n// Lists\nconst list = await sendly.contacts.lists.create({ name: 'VIPs' });\nconst { addedCount } = await sendly.contacts.lists.addContacts(list.id, [contact.id]);\nawait sendly.contacts.lists.removeContact(list.id, contact.id);\nconst { lists } = await sendly.contacts.lists.list();\n```\n\n### List health\n\nContacts that fail with a terminal bad-number error, or that a carrier lookup\nreports as non-SMS-capable, are flagged with an `invalidReason`\n(`landline`, `invalid_number`, `non_sms_capable`) and skipped by future\ncampaigns. Clear a flag you disagree with — the clearance survives later\nlookups.\n\n```typescript\n// Run a carrier lookup (asynchronous; watch contacts.lookup_completed)\nawait sendly.contacts.checkNumbers({ listId: 'lst_xxx', force: false });\n\n// Clear flags, one or in bulk (ids OR listId, never both; max 10,000 ids)\nawait sendly.contacts.markValid('cnt_xxx');\nconst { cleared } = await sendly.contacts.bulkMarkValid({ listId: 'lst_xxx' });\n```\n\n## Conversations, Labels & Drafts\n\nInbound replies are threaded per phone number. Conversations carry unread\ncounts, tags, labels, and an AI reply suggester.\n\n```typescript\n// List and read threads\nconst { data: conversations, pagination } = await sendly.conversations.list({ status: 'active' });\nconst thread = await sendly.conversations.get(conversations[0].id, {\n includeMessages: true,\n messageLimit: 50,\n});\nconsole.log(thread.unreadCount, thread.messages?.data.length);\n\n// Reply, then housekeeping\nawait sendly.conversations.reply(thread.id, { text: 'On our way!' });\nawait sendly.conversations.markRead(thread.id);\nawait sendly.conversations.close(thread.id);\nawait sendly.conversations.reopen(thread.id);\nawait sendly.conversations.update(thread.id, { tags: ['vip'], metadata: { crmId: 'c_1' } });\n\n// AI: suggested replies, and the thread packaged for your own model\nconst { suggestions } = await sendly.conversations.suggestReplies(thread.id);\nconst { context, tokenEstimate } = await sendly.conversations.getContext(thread.id);\n\n// Labels\nconst label = await sendly.labels.create({ name: 'Billing', color: '#0B6E4F' });\nawait sendly.conversations.addLabels(thread.id, [label.id]);\nawait sendly.conversations.removeLabel(thread.id, label.id);\nconst { data: labels } = await sendly.labels.list();\n\n// Drafts — queue a reply for a human to approve\nconst draft = await sendly.drafts.create({ conversationId: thread.id, text: 'Proposed reply' });\nawait sendly.drafts.update(draft.id, { text: 'Better reply' });\nawait sendly.drafts.approve(draft.id); // sends it\nawait sendly.drafts.reject(draft.id, 'Wrong tone');\nconst { data: drafts } = await sendly.drafts.list({ status: 'pending' });\n\n// Auto-label rules — label or close threads by AI intent/sentiment\nawait sendly.rules.create({\n name: 'Escalate angry complaints',\n conditions: { intent: 'complaint', sentiment: 'negative', sentimentConfidenceMin: 0.8 },\n actions: { addLabels: [label.id], closeConversation: false },\n});\nconst { data: rules } = await sendly.rules.list();\n```\n\n## Media (MMS)\n\nUpload a file, then attach its URL to a message. On SMS/MMS, `mediaUrls` only\naccepts URLs returned by `media.upload()` (max 10 per message); any other URL is\nrefused with `invalid_request`.\n\n```typescript\nimport { readFileSync } from 'node:fs';\n\nconst media = await sendly.media.upload(readFileSync('photo.jpg'), {\n filename: 'photo.jpg',\n contentType: 'image/jpeg',\n});\nconsole.log(media.id, media.url, media.sizeBytes);\n\nawait sendly.messages.send({\n to: '+15125550123',\n text: 'Check this out!',\n mediaUrls: [media.url],\n});\n```\n\n## Business Upgrade (toll-free entity upgrade)\n\nMove a workspace onto a properly registered business entity: pre-flight the\ncandidate details, start the upgrade (which reserves a new toll-free number and\nsubmits it for carrier review), then follow it. The workspace is addressed by\nits id (a UUID).\n\n```typescript\nconst workspaceId = '9b2f4c1e-7d3a-4e5b-8c6f-0a1b2c3d4e5f';\n\n// The preflight checks only what you pass; it fills nothing in from the\n// workspace's record. Pass every field the upgrade will use (address,\n// contact, use case, useCaseSummary, additionalInformation, ...), or the\n// verdict is 'blocked' for the missing ones.\nconst report = await sendly.businessUpgrade.preflight({\n businessName: 'Acme Holdings LLC',\n brn: '12-3456789',\n brnType: 'EIN',\n brnCountry: 'US',\n entityType: 'PRIVATE_PROFIT',\n});\nconsole.log(report.verdict); // 'ready', 'warnings' or 'blocked'\nfor (const issue of report.issues) console.log(issue.field, issue.message);\n\nconst started = await sendly.businessUpgrade.start(\n workspaceId,\n {\n businessName: 'Acme Holdings LLC',\n brn: '12-3456789',\n brnType: 'EIN',\n brnCountry: 'US',\n entityType: 'PRIVATE_PROFIT',\n },\n { einDoc: { buffer: pdfBuffer, filename: 'ein.pdf' } },\n);\nconsole.log(started.pendingVerificationId, started.status); // ..., 'provisioning'\n\n// The new number and verification are set up in the background: poll status\nconst { pending } = await sendly.businessUpgrade.status(workspaceId);\nconsole.log(pending?.status, pending?.tollFreeNumber, pending?.rejectionReason);\nawait sendly.businessUpgrade.cancel(workspaceId);\n```\n\n## Phone Numbers\n\nDiscover, buy, and manage the phone numbers you own.\n\n```typescript\n// Browse what's available and buy one\nconst { countries } = await sendly.numbers.listCountries();\nconst { numbers } = await sendly.numbers.listAvailable({ country: 'GB', type: 'mobile' });\nawait sendly.numbers.buy({\n phoneNumber: numbers[0].phoneNumber,\n countryCode: numbers[0].country,\n phoneNumberType: numbers[0].numberType,\n monthlyCost: numbers[0].monthlyCost\n});\n\n// List the numbers you own\nconst { numbers: owned } = await sendly.numbers.list();\n\n// Get one by id (includes isDefault)\nconst number = await sendly.numbers.get('num_xxx');\nconsole.log(`${number.phoneNumber} — default: ${number.isDefault}`);\n\n// Make a number your workspace's default sender (must be active)\nawait sendly.numbers.update('num_xxx', { isDefault: true });\n\n// Cancel a scheduled release (\"keep this number\")\nawait sendly.numbers.update('num_xxx', { pendingCancellation: false });\n\n// Release a number. A live paid purchase is cancelled at period end.\nconst result = await sendly.numbers.release('num_xxx');\nif (result.scheduled) {\n console.log(`Releases at ${result.scheduledReleaseAt}`);\n} else {\n console.log('Released');\n}\n```\n\n## Branded Links\n\nMint branded short links for a destination URL, list them with click\nanalytics, and disable an individual link. Requires the `url_shortener`\nrollout flag on your account.\n\n```typescript\n// Shorten a URL\nconst link = await sendly.links.create({ url: 'https://acme.example/welcome' });\nconsole.log(link.shortUrl); // https://sendly.live/l/Ab3xY7\n\n// List your links with click counts\nconst { links, total } = await sendly.links.list({ limit: 20 });\nfor (const l of links) {\n console.log(`${l.shortUrl} -> ${l.destinationUrl} (${l.clickCount} clicks)`);\n}\n\n// Disable (kill) a link, or re-enable it\nawait sendly.links.disable(link.code);\nawait sendly.links.enable(link.code);\n```\n\n## 10DLC (Local Number Texting)\n\nRegister your business for carrier review so you can text from local (10-digit) US numbers. The flow is brand → campaign → assign number. Writes require a live API key.\n\n```typescript\n// 1. Register a brand for carrier review\nconst { data: brand } = await sendly.tenDlc.createBrand({\n legalName: 'Acme Holdings LLC',\n ein: '12-3456789',\n website: 'https://acme.example',\n email: 'ops@acme.example',\n});\n\n// Poll until the brand is verified (or failed, with failureReasons). It can\n// pass through awaiting_review (Sendly reviews it first), changes_requested\n// and provisioning before the carriers see it as pending.\nconst { data: refreshed } = await sendly.tenDlc.getBrand(brand.id);\nconsole.log(refreshed.status); // \"pending\" -> \"verified\"\n\n// 2. Pre-check your use case, then create a campaign\nconst { data: check } = await sendly.tenDlc.qualify(brand.id, 'MIXED');\nif (check.qualified) {\n const { data: campaign } = await sendly.tenDlc.createCampaign({\n brandId: brand.id,\n useCase: 'MIXED',\n description: 'Order updates and support replies for Acme customers',\n messageFlow: 'Customers opt in at checkout on acme.example',\n sampleMessages: ['Your order #123 has shipped!'],\n optOutKeywords: 'STOP',\n });\n\n // Poll until carriers approve. \"awaiting_review\" means Sendly reviews it\n // first; \"changes_requested\" comes with a reviewNote saying what to change.\n const { data: approved } = await sendly.tenDlc.getCampaign(campaign.id);\n console.log(approved.status); // \"pending\" -> \"active\"\n if (approved.status === 'changes_requested') console.log(approved.reviewNote);\n console.log(approved.throughput?.tier); // e.g. \"Standard\"\n\n // 3. Assign a number you own — it can send once the assignment is Active\n const { data: assignment } = await sendly.tenDlc.assignNumber(\n campaign.id,\n '+15125550123',\n );\n console.log(assignment.status); // \"Under review\" -> \"Active\"\n}\n\n// List everything\nconst { data: brands } = await sendly.tenDlc.listBrands();\nconst { data: campaigns } = await sendly.tenDlc.listCampaigns();\nconst { data: assignments } = await sendly.tenDlc.listAssignments();\n```\n\n## Short Codes\n\nA short code is a 5 or 6 digit US sender, not a separate channel — sends bill\nas ordinary SMS credits. Getting one is an application, not a purchase: you\nfill it in, Sendly reviews it, the carrier forms are signed, Sendly files them,\nand each carrier certifies the code separately (an 8-12 week clock). The digits\nare assigned at the end, so `shortCode` is `null` until then.\n\nReads need the `short_codes:read` scope and writes `short_codes:write`. There\nis no `create` method — the first `update()` creates the application, and a\nworkspace has at most one open application at a time.\n\n```typescript\n// Where the application stands, what it still needs, and the quoted lease\nconst view = await sendly.shortCodes.application.get();\nconsole.log(view.application.reviewStatus); // 'draft'\nconsole.log(view.quote.monthlyUsd, view.quote.setupUsd, view.quote.currency); // never auto-billed\nconsole.log(view.missingDocuments); // carrier forms still outstanding\nconsole.log(view.verification?.state); // the business verification it needs\nfor (const c of view.carriers.byCarrier ?? []) console.log(c.label, c.status);\nif (!view.editable) console.log(view.lockMessage);\n\n// Save answers (creates the application on the first call). Fields Sendly or\n// the carriers own — the digits, status, review state — are ignored and named\n// back in ignoredFields.\nawait sendly.shortCodes.application.update({\n useCase: 'Delivery alerts for Acme orders',\n optInFlow: 'Customers tick a box at checkout on acme.example',\n messageFrequency: '4 messages per month',\n sampleMessages: ['Acme: order #4821 is out for delivery. Reply STOP to opt out.'],\n helpResponse: 'Acme: email help@acme.example for support.',\n stopConfirmation: 'You are unsubscribed from Acme alerts.',\n privacyPolicyUrl: 'https://acme.example/privacy',\n termsUrl: 'https://acme.example/terms',\n codeType: 'random', // or 'vanity' (costs more, subject to availability)\n orderType: 'new', // or 'migration' from another provider\n});\n\n// Dry-run the carrier rules without changing anything. Unsaved answers can be\n// passed in and are checked on top of what is saved.\nconst { ok, issues } = await sendly.shortCodes.application.check();\nfor (const issue of issues) console.log(issue.path, issue.message);\n\n// Submit to Sendly for review. Submitting twice is safe.\nconst submitted = await sendly.shortCodes.application.submit();\nconsole.log(submitted.application.reviewStatus); // 'awaiting_review'\nconsole.log(submitted.alreadySubmitted); // true on a repeat call\n\n// The codes leased to the workspace\nconst { shortCodes } = await sendly.shortCodes.list();\nconst sendable = shortCodes.filter((code) => code.status === 'active');\nconsole.log(shortCodes.map((code) => `${code.shortCode ?? 'pending'}: ${code.status} (${code.reviewStatus})`));\n```\n\nReview states move `draft` → `awaiting_review` → `approved_for_filing` →\n`filed`, with `changes_requested` bouncing it back to you (editable again) and\n`rejected` ending it. The code itself is `requested`, then `provisioning`,\n`parked` (leased, not yet certified), `active` — the only status that can send —\nand `suspended` or `cancelled`.\n\nRefusals: `short_codes_not_enabled` (404) when short codes are not switched on\nfor the account, `short_code_locked` (409) once the application is with Sendly\nor the carriers, and `short_code_invalid_application` (422) with an `errors`\narray naming every field. The `short_code.action_required`, `short_code.filed`,\n`short_code.rejected` and `short_code.live` webhooks track it without polling.\n\n## WhatsApp\n\nConnect a number you own to WhatsApp ($19 one-time, no monthly fee), create\nMeta-reviewed message templates, and send on the `whatsapp` channel.\nConnecting the first number always ends with a human step: hand the\n`connectUrl` to your user - they open it in a browser and log in with\nFacebook to link their WhatsApp Business Account. Further numbers can join\nthat account by code, without Facebook. Free-form text and media only deliver inside an open 24-hour\nwindow (the recipient messaged you in the last 24h); an approved template\nworks anytime.\n\nSends go through `messages.send` with `channel: \"whatsapp\"` and need\n`sms:send`, not `whatsapp:write`. Reads (`signup.get`, templates, the window,\nsenders, sender profiles and conversational components) need `whatsapp:read`\nand accept test keys. Signup (with `verify` and `resend`), template\ncreate/edit/delete and sender edits (profile, photo, conversational\ncomponents, calling) need `whatsapp:write` and a live key (otherwise 403\n`whatsapp_requires_live_key`). Sends need a live key too. In a team\nworkspace, connecting and sender edits need an owner or admin\n(`settings:write`), and template writes need an owner, admin or member\n(`templates:write`). A missing role returns 403 `insufficient_permissions`.\n\nWhatsApp is enabled per person: the user who owns the API key, not the\nworkspace. While it is off, sends return 403 `whatsapp_not_enabled` and the\n`/api/v1/whatsapp/*` management routes return 404 `not_found`.\n\n```typescript\n// 1. Connect a number (a person must finish the connect URL in a browser)\nconst signup = await sendly.whatsapp.signup.create({\n phoneNumber: '+15125550123',\n});\nconsole.log(`Open ${signup.connectUrl} and log in with Facebook`);\n// ...poll sendly.whatsapp.signup.get(signup.id) until status === 'active'.\n// After the Facebook step it stays 'registering' while WhatsApp activates the\n// number. Activation usually takes a few minutes but can take hours. If it\n// hasn't finished about 6 hours after the session began, the session fails\n// with registration_timeout and the fee is refunded. 'failed' comes with\n// failureReasons. If the connection fails, the $19 fee is refunded\n// automatically; once a number has connected, a later disconnect gets\n// nothing back.\n\n// 2. Create a template (Meta reviews it, usually 24-48h). category is\n// required (UTILITY, AUTHENTICATION or MARKETING) with no default, and an\n// update can't change it.\nconst template = await sendly.whatsapp.templates.create({\n sender: '+15125550123',\n name: 'order_shipped',\n language: 'en_US',\n category: 'UTILITY',\n body: 'Hi {{1}}, your order {{2}} has shipped!',\n examples: { '1': 'Sam', '2': '#4821' },\n});\n// ...poll sendly.whatsapp.templates.list() until its status === 'APPROVED'\n// (a rejected template should be edited with templates.update() and\n// resubmitted - deleting locks its name for ~30 days). A `header` is fixed\n// text: one containing {{n}} is refused with template_header_variable_unsupported.\n\n// 3. Send - free-form inside an open 24h window, template anytime\nconst { open } = await sendly.whatsapp.window({\n from: '+15125550123',\n to: '+15125550142',\n});\nconst message = open\n ? await sendly.messages.send({\n channel: 'whatsapp',\n to: '+15125550142',\n from: '+15125550123',\n text: 'Your table is ready!',\n })\n : await sendly.messages.send({\n channel: 'whatsapp',\n to: '+15125550142',\n from: '+15125550123',\n template: {\n name: 'order_shipped',\n language: 'en_US',\n variables: { '1': 'Sam', '2': '#4821' },\n },\n });\nconsole.log(message.whatsapp.kind); // 'text' or 'template'\n\n// Media with a caption (window-bound, one attachment per message)\nawait sendly.messages.send({\n channel: 'whatsapp',\n to: '+15125550142',\n from: '+15125550123',\n text: 'Here is the menu',\n mediaUrls: ['https://acme.example/menu.jpg'],\n});\n\n// List your connected senders\nconst { senders } = await sendly.whatsapp.senders.list();\nfor (const s of senders) {\n console.log(`${s.phoneNumber} (${s.displayName}) - ${s.status}`);\n}\n\n// Read and update a sender's business profile (what recipients see)\nconst profile = await sendly.whatsapp.senders.getProfile('+15125550123');\nconsole.log(profile.displayName, profile.about);\n\nawait sendly.whatsapp.senders.updateProfile('+15125550123', {\n about: 'Fresh roasts daily', // max 139 chars\n description: 'Small-batch coffee, roasted in-house every morning.', // max 512\n website: 'https://acme.example',\n});\n\n// Profile photo: a JPEG or PNG up to 5 MB, square, at least 192 px wide\nawait sendly.whatsapp.senders.uploadProfilePhoto(\n '+15125550123',\n fs.readFileSync('logo.png'),\n { contentType: 'image/png' },\n);\nawait sendly.whatsapp.senders.deleteProfilePhoto('+15125550123');\n\n// Ice breakers (up to 4) and \"/\" commands (up to 30). Each list you pass\n// replaces the stored one; [] clears it.\nawait sendly.whatsapp.senders.updateConversationalComponents('+15125550123', {\n iceBreakers: ['What are your hours?', 'Book a table'],\n commands: [{ command: 'menu', description: \"See today's menu\" }],\n});\nconst { iceBreakers, commands } =\n await sendly.whatsapp.senders.getConversationalComponents('+15125550123');\n\n// Let WhatsApp users call the number. Calls must be on for the number first\n// (voice_not_enabled otherwise); they ring like phone calls. There is no API\n// for placing WhatsApp calls.\nawait sendly.whatsapp.senders.setCalling('+15125550123', { enabled: true });\n\n// Add another number to an account you already connected: no Facebook step.\n// Same $19 fee, refunded if it fails. WhatsApp sends the number a 6-digit code.\nconst account = senders.find((s) => s.status === 'active' && s.businessAccountId);\nconst added = await sendly.whatsapp.signup.create({\n phoneNumber: '+15125550124',\n businessAccountId: account!.businessAccountId!,\n verificationMethod: 'sms', // or 'voice'\n});\n// added.status === 'verifying'. signup.get() returns verificationCode once the\n// text reaches the number; or enter the code yourself.\nconst pending = await sendly.whatsapp.signup.get(added.id);\nif (pending.verificationCode) {\n await sendly.whatsapp.signup.verify(added.id, pending.verificationCode);\n}\n// No code? Ask again (30 seconds apart; leaving out the method sends a text)\nawait sendly.whatsapp.signup.resend(added.id, 'voice');\n```\n\n`senders.list()` items also carry `businessAccountId` (null while `pending`),\n`businessName` (null while `pending`, or when the account has no business\nname on file), `callingEnabled`, and `outboundCallingAllowed`, which is false\nfor +1, +20, +84 and +234 numbers. A signup that is `verifying` carries\n`verificationMethod` and `verificationAttemptsRemaining`; after 5 wrong codes\nit fails with `verification_failed` and the fee is refunded. Calls carry\n`channel` (`phone`, `whatsapp` or `browser`).\n\n`verificationCode` comes only from `signup.get()`. Until a code has been\nsubmitted, it is the newest code that has arrived since the signup started, so\nafter a resend it still shows the earlier code until the new one arrives. Once\nWhatsApp has checked a code, only a code that arrived after the last\nsubmission or resend is returned. A submission answered with 502\n`whatsapp_verification_unavailable` is not counted, so the same unchecked code\ncan come back, and submitting it again is safe.\n\nPricing: free-form text or media inside the 24-hour window costs 1 credit\neach for the first 1,000 per sending number per calendar month (UTC), then\nthe destination's utility template price; countries without a listed price\nuse the default utility price of 12 credits. Templates are priced by category\nand destination country; countries without a listed price use 33\n(marketing), 12 (utility) and 12 (authentication) credits. A failed send\ngives its slot back.\n\n`sendly.whatsapp.window()` returns exactly `{ open, expiresAt }`. With no\nwindow on record, `open` is false and `expiresAt` is null; after a window\nhas expired, `open` is false and `expiresAt` is the past expiry.\n\nRefusals worth handling:\n\n- `whatsapp_unavailable` (503): only `signup.create` returns it, while\n WhatsApp connections are temporarily unavailable. Nothing is charged; the\n body carries `retryAfter: 3600` (read it as `error.response.retryAfter`)\n and the response a `Retry-After: 3600` header. The SDK retries it like any\n `5xx` before throwing. No send returns it.\n- `whatsapp_signup_limit_reached` (429): 5 failed, charged signups in 24\n hours. Final; try again the next day.\n- `whatsapp_window_closed` (422): free-form text or media outside the 24-hour\n window. Send an approved template instead.\n- `whatsapp_send_failed`: a `422` when WhatsApp refused the message (final;\n cached under the idempotency key and replayed for 24 hours), or a `502`\n when the message provably never reached the carrier, so it was not sent\n and is safe to send again. A `502` is never cached, and the SDK retries it\n with the same idempotency key.\n- `whatsapp_send_unconfirmed` (409): the outcome is unknown. The message was\n marked failed and refunded but may still be delivered, so check before\n sending it again (it could arrive twice). It is not retried automatically.\n- `whatsapp_not_enabled` (403) on sends while WhatsApp is off for the key's\n owner, and `whatsapp_requires_live_key` (403) for a test key on a send or\n a write.\n- `whatsapp_sender_not_connected` (404) from `templates.create`, checked\n before anything else.\n- `template_*` codes (400, thrown as a `SendlyError`) when `templates.create`\n or `update` fails its pre-flight checks: `template_category_invalid`\n (category missing or not one of the three),\n `template_authentication_otp_button_required`,\n `template_authentication_no_links` (a link in the body or a URL button on\n an authentication template) and `template_header_variable_unsupported`.\n A marketing template without an opt-out button only gets a warning.\n- Profile photo: `file_required` and `whatsapp_profile_photo_invalid` (400),\n `whatsapp_profile_photo_too_large` (413), `whatsapp_profile_update_failed`\n (502). Conversational components: `invalid_request` (400) with the reason,\n `whatsapp_conversational_components_fetch_failed` and\n `whatsapp_conversational_components_update_failed` (502). Calling:\n `voice_not_enabled` (409), `whatsapp_calling_unavailable` (422, WhatsApp\n only allows calling once the account may message 2,000 people a day and\n the display name is approved), `whatsapp_calling_update_failed` (502).\n- Adding a number by code: `whatsapp_business_account_not_found` (404),\n `display_name_required` (400), `whatsapp_signup_in_progress` and\n `whatsapp_already_enabled` (409), and `whatsapp_verification_start_failed`\n (422 refused, 502 unreachable; the fee is refunded either way). A Facebook\n `signup.create` for a number being added by code gets\n `whatsapp_verification_in_progress` (409). `verify`:\n `invalid_verification_code` (400, not 6 digits),\n `whatsapp_verification_code_invalid` (422, with\n `error.response.attemptsRemaining`), `whatsapp_verification_failed` (409,\n too many wrong codes), `whatsapp_verification_busy` (409, retry),\n `whatsapp_verification_unavailable` and `whatsapp_activation_pending`\n (502). `resend`: `whatsapp_verification_resend_too_soon` (429, wait\n `error.response.retryAfter` seconds) and\n `whatsapp_verification_resend_failed` (422 or 502). Both answer\n `signup_not_active` (409) once the signup stops waiting for a code, and\n `signup_not_found` (404). The SDK never retries a `5xx`, a timeout\n or a network error from `signup.create` with a `businessAccountId` or from\n `verify`; it retries `resend` like any other call.\n\n## RCS\n\nSend branded, verified-sender messages on Android: rich cards, suggestion\nchips, and read receipts. Sending as your brand requires an RCS agent (the\nverified identity recipients see). Registration is self-serve, from the\ndashboard or the API: draft a brand and an agent, submit them for review\n(Sendly reviews first, then the carrier network), test on invited devices,\nthen request launch. Text messages automatically fall back to SMS when the\nrecipient's device or network doesn't support RCS (billed as SMS; suggestion\nchips are dropped); rich cards have no SMS form and respond 422 instead.\nSending requires a live API key.\n\n### Registering an agent\n\nReads need the `rcs:read` scope and writes `rcs:write`. Every brand and\nagent field is optional while drafting; required-field checks run at\n`submit`, which lists each gap in `error.response.errors`. Logo, hero, and\ncall-to-action media must be public `https://` URLs - uploading assets is\ndashboard-only. RCS registration is available to US businesses for now.\n\n```typescript\n// 1. Draft a brand - prefill it from business details already on file\nconst dossier = await sendly.rcs.dossier.get();\nconst { brand } = await sendly.rcs.brands.create({\n ...dossier.brand,\n displayName: 'Acme Coffee',\n legalName: 'Acme Coffee LLC',\n legalEntityType: 'LIMITED_LIABILITY_COMPANY',\n organizationType: 'PRIVATE_PROFIT',\n websiteUrl: 'https://acme.example',\n ein: '12-3456789',\n address: { line1: '100 Main St', city: 'Chicago', state: 'IL', postalCode: '60601', countryCode: 'US' },\n contact: { firstName: 'Sam', lastName: 'Lee', email: 'sam@acme.example', phoneNumber: '+13125550100' },\n});\n\n// 2. Draft the agent recipients will see\nconst { agent } = await sendly.rcs.agents.create({\n brandId: brand.id,\n displayName: 'Acme Coffee',\n useCase: 'MULTI_USE',\n basics: {\n description: 'Order updates and support for Acme Coffee customers',\n logoUrl: 'https://acme.example/rcs/logo.png', // public https URL\n heroUrl: 'https://acme.example/rcs/hero.png',\n brandColor: '#0B6E4F',\n privacyPolicyUrl: 'https://acme.example/privacy',\n termsAndConditionsUrl: 'https://acme.example/terms',\n },\n});\n\n// 3. Submit for review - an idempotency key means a retry never re-notifies reviewers\nconst { stage } = await sendly.rcs.agents.submit(agent.id, {\n idempotencyKey: `rcs-submit-${agent.id}`,\n});\nconsole.log(stage); // \"in_review\"\n\n// Poll for progress: in_review -> brand_verification -> agent_review -> testing -> ...\nconst { agent: current } = await sendly.rcs.agents.get(agent.id);\nconsole.log(current.customerStage, current.reviewNote);\n\n// 4. Once the stage is 'testing': invite your devices and fill in the campaign\nawait sendly.rcs.agents.setTestDevices(agent.id, [\n { phoneNumber: '+13125550100', label: \"Sam's Pixel\" },\n]);\nawait sendly.rcs.agents.update(agent.id, {\n campaign: {\n companyOverview: 'Acme Coffee runs 12 cafes and an online store.',\n agentOverview: 'Order confirmations, pickup alerts, and support replies',\n interactions: [{ interactionType: 'TRANSACTIONAL_UPDATES', description: 'Order status' }],\n messageExamples: [\n 'Acme Coffee: order #4821 is being roasted. Reply STOP to opt out.',\n 'Your order #4821 is ready for pickup!',\n 'Thanks for visiting - reply HELP for support.',\n ],\n consentSettings: {\n optInMethods: [{ methodType: 'WEBSITE', description: 'Checkout checkbox' }],\n callToAction: 'Text me order updates',\n callToActionUrl: 'https://acme.example/checkout',\n callToActionMediaUrl: 'https://acme.example/rcs/opt-in.png',\n doubleOptIn: false,\n optInMessage: 'Welcome to Acme Coffee updates. Reply STOP to opt out.',\n helpResponse: 'Acme Coffee: email help@acme.example for support.',\n optOutResponse: 'You have been unsubscribed from Acme Coffee updates.',\n },\n },\n});\n\n// 5. Request launch - the agent can reach everyone once the stage is 'live'\nawait sendly.rcs.agents.requestLaunch(agent.id, { testUrl: 'https://acme.example/rcs-test' });\n\n// Everything at a glance\nconst registration = await sendly.rcs.registration.get();\nconsole.log(registration.stage, registration.agent?.displayName);\n```\n\n### Sending\n\n```typescript\n// Your registered agents ('testing' or 'approved' agents are sendable)\nconst { agents } = await sendly.rcs.agents.list();\nconsole.log(agents[0].name, agents[0].status, agents[0].sendable);\n\n// Optionally pre-flight a recipient (live carrier-backed probe)\nconst { capable, features } = await sendly.rcs.capability({\n to: '+15125550123',\n});\n\n// Text with suggestion chips - falls back to SMS for non-RCS recipients\nconst message = await sendly.messages.send({\n channel: 'rcs',\n to: '+15125550123',\n text: 'Your table is ready!',\n suggestions: [\n { reply: { text: 'On my way', postbackData: 'omw' } },\n { action: { text: 'View menu', postbackData: 'menu', url: 'https://acme.example/menu' } },\n ],\n});\n\n// The response tells you which leg delivered\nif (message.channel === 'rcs') {\n console.log(message.rcs.agentName); // delivered over RCS\n} else {\n console.log(message.fellBackTo); // 'sms'\n console.log(message.rcs.suggestionsDropped); // true - chips have no SMS form\n}\n\n// Rich card (RCS-capable recipients only - no SMS form)\nawait sendly.messages.send({\n channel: 'rcs',\n to: '+15125550123',\n card: {\n title: 'Your order has shipped',\n description: 'Arriving Thursday',\n mediaUrl: 'https://acme.example/package.jpg', // public JPEG/PNG/GIF\n orientation: 'vertical',\n suggestions: [\n { action: { text: 'Track it', postbackData: 'track', url: 'https://acme.example/track' } },\n ],\n },\n});\n\n// Opt out of the SMS fallback to get a 422 for non-RCS recipients instead\nawait sendly.messages.send({\n channel: 'rcs',\n to: '+15125550123',\n text: 'Your table is ready!',\n fallbackToSms: false,\n});\n```\n\n## Voice Calls\n\nPlace phone calls that one of your workspace's AI agents handles, follow\nthem while they ring and run, read the transcript, hang up early, and fetch\nrecordings. Reads need the `calls:read` scope and writes `calls:write`;\nwrites need a live API key. Destinations are US and Canadian numbers.\n\nCalls are prepaid from your credit balance per started minute: an\nagent-handled outbound call is 10 credits a minute (2 for the call, 8 for\nthe agent), and unanswered calls cost nothing. The `from` number must be\nvoice-enabled with an emergency address registered, in the dashboard (Calls →\nSettings) or from code with [`sendly.voice.numbers`](#configure-voice);\n`sendly.numbers.list()` shows `voiceEnabled` and `voiceMode` per number. Voice is being enabled workspace by workspace; until it is on\nfor yours, every call method responds `404 voice_not_enabled`.\n\n```typescript\n// Have an agent call someone (from is optional with one voice-enabled number)\nconst call = await sendly.calls.create({\n to: '+15125550142',\n agentId: '3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b',\n from: '+15125550123',\n context: 'You are calling Jordan to confirm the 3pm appointment on Tuesday.',\n metadata: { crmId: 'lead_8812' },\n});\nconsole.log(call.id, call.status); // \"6f1c2d3e-...\", \"ringing\"\n\n// List calls, newest first, with filters and pagination\nconst { data, pagination } = await sendly.calls.list({\n status: 'completed',\n direction: 'outbound',\n limit: 20,\n});\nfor (const c of data) {\n console.log(`${c.to} ${c.durationSecs}s ${c.creditsCharged} credits ${c.hangupClass}`);\n}\nif (pagination.hasMore) {\n await sendly.calls.list({ status: 'completed', limit: 20, offset: 20 });\n}\n\n// Retrieve a call; agent-handled calls include the transcript\nconst current = await sendly.calls.get(call.id);\nfor (const line of current.transcript ?? []) {\n console.log(`${line.speaker}: ${line.text}`);\n}\n\n// End a call early: ringing -> cancelled, active -> completed\nawait sendly.calls.hangup(call.id);\n\n// Fetch the recording (Ogg/Opus). The signed URL is valid for five minutes.\n// Agent calls are stereo: the agent on the left channel, the other party on the right.\nconst recording = await sendly.calls.recording(call.id);\nif (recording.status === 'ready') {\n console.log(recording.url, recording.expiresAt); // audio/ogg\n}\n```\n\nRefusals come back as `SendlyError` with a code: `agent_not_found` (404),\n`agent_disabled` (409), `from_number_required` (400), `e911_required` (428,\nregister an emergency address first","readmeFilename":"README.md"}
![\"Sendly](\"https://raw.githubusercontent.com/SendlyHQ/sendly-node/main/.github/header.svg\")
\n![\"npm](\"https://img.shields.io/npm/v/@sendly/node.svg?style=flat-square\")
\n ![\"license\"](\"https://img.shields.io/npm/l/@sendly/node.svg?style=flat-square\")
\n