@messagebird/sdk 0.4.2 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -0
- package/dist/index.d.mts +411 -368
- package/dist/index.mjs +174 -251
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
package/dist/index.d.mts
CHANGED
|
@@ -89,6 +89,17 @@ interface ErrorNextAction {
|
|
|
89
89
|
/** Permission scope the recovery operation requires, when it is scoped. */
|
|
90
90
|
scope?: string;
|
|
91
91
|
}
|
|
92
|
+
/** One verification requirement blocking the action, with the flow that resolves it. */
|
|
93
|
+
interface UnmetGate {
|
|
94
|
+
/** Stable identifier for the verification requirement. */
|
|
95
|
+
slug: string;
|
|
96
|
+
/** Human-readable name of the verification requirement. */
|
|
97
|
+
name: string;
|
|
98
|
+
/** The requirement's current state. */
|
|
99
|
+
status: string;
|
|
100
|
+
/** How to resolve this requirement. */
|
|
101
|
+
remediation_kind: string;
|
|
102
|
+
}
|
|
92
103
|
/** Constructor fields shared by every API error, mapped from the wire body. */
|
|
93
104
|
interface BirdAPIErrorFields {
|
|
94
105
|
statusCode: number;
|
|
@@ -111,6 +122,8 @@ interface BirdAPIErrorFields {
|
|
|
111
122
|
remediation?: string;
|
|
112
123
|
/** Operations that resolve this error, in the order to try them (ADR-0073). */
|
|
113
124
|
next?: ErrorNextAction[];
|
|
125
|
+
/** Verification requirements blocking this action, when it is blocked pending verification. */
|
|
126
|
+
unmetGates?: UnmetGate[];
|
|
114
127
|
}
|
|
115
128
|
/** The server returned an error body. Base for every `type`-specific class. */
|
|
116
129
|
declare class BirdAPIError extends BirdError {
|
|
@@ -124,6 +137,7 @@ declare class BirdAPIError extends BirdError {
|
|
|
124
137
|
readonly vendorCode?: string;
|
|
125
138
|
readonly remediation?: string;
|
|
126
139
|
readonly next?: ErrorNextAction[];
|
|
140
|
+
readonly unmetGates?: UnmetGate[];
|
|
127
141
|
constructor(fields: BirdAPIErrorFields);
|
|
128
142
|
}
|
|
129
143
|
/** 401 — authentication failed or missing. */
|
|
@@ -265,10 +279,10 @@ type EventSmsUndeliveredData = EventSmsBase & {
|
|
|
265
279
|
error: SmsError;
|
|
266
280
|
};
|
|
267
281
|
/**
|
|
268
|
-
* Bird-stable failure reason. `invalid_destination` — the number is not assigned, ported out, or malformed. `unreachable` — handset off or out of coverage. `blocked_by_carrier` — the carrier filtered the message. `blocked_by_recipient` — the recipient device blocked the sender. `landline_unreachable` — the destination is a landline that does not accept SMS. `content_rejected` — the carrier rejected the content. `sender_unregistered` — the sender is not registered for the destination. `recipient_opted_out` — the recipient is on a suppression list. `provider_unavailable` — an upstream failure after retries. `unknown` — an unmapped failure.
|
|
282
|
+
* Bird-stable failure reason. `invalid_destination` — the number is not assigned, ported out, or malformed. `unreachable` — handset off or out of coverage. `blocked_by_carrier` — the carrier filtered the message. `blocked_by_recipient` — the recipient device blocked the sender. `landline_unreachable` — the destination is a landline that does not accept SMS. `content_rejected` — the carrier rejected the content. `sender_unregistered` — the sender is not registered for the destination. `recipient_opted_out` — the recipient is on a suppression list. `provider_unavailable` — an upstream failure after retries. `insufficient_balance` — the workspace wallet had insufficient balance to send the message. `unknown` — an unmapped failure.
|
|
269
283
|
*
|
|
270
284
|
*/
|
|
271
|
-
type SmsErrorCode = "invalid_destination" | "unreachable" | "blocked_by_carrier" | "blocked_by_recipient" | "landline_unreachable" | "content_rejected" | "sender_unregistered" | "recipient_opted_out" | "provider_unavailable" | "unknown";
|
|
285
|
+
type SmsErrorCode = "invalid_destination" | "unreachable" | "blocked_by_carrier" | "blocked_by_recipient" | "landline_unreachable" | "content_rejected" | "sender_unregistered" | "recipient_opted_out" | "provider_unavailable" | "insufficient_balance" | "unknown";
|
|
272
286
|
/**
|
|
273
287
|
* Failure detail for a message that could not be delivered or was rejected. Null when there is no failure.
|
|
274
288
|
*/
|
|
@@ -605,22 +619,7 @@ type EventEmailMailboxMessageSent = {
|
|
|
605
619
|
data: EventEmailMailboxMessageSentData;
|
|
606
620
|
};
|
|
607
621
|
/**
|
|
608
|
-
*
|
|
609
|
-
*/
|
|
610
|
-
type EventEmailMailboxMessageReceivedUnauthenticated = {
|
|
611
|
-
/**
|
|
612
|
-
* Event type.
|
|
613
|
-
*/
|
|
614
|
-
type: "email_mailbox.message_received_unauthenticated";
|
|
615
|
-
/**
|
|
616
|
-
* When the event occurred.
|
|
617
|
-
*/
|
|
618
|
-
timestamp: string;
|
|
619
|
-
data: EventEmailMailboxMessageReceivedData;
|
|
620
|
-
};
|
|
621
|
-
type InboundEmailMessageId = string;
|
|
622
|
-
/**
|
|
623
|
-
* Payload shared by the email_mailbox.message_received event family. Carries identifiers, threading, disposition, authentication results, and the extracted text — enough for an agent to act without a fetch. Fetch original source (while within its 30-day window) via the thread-member endpoints.
|
|
622
|
+
* Payload for the email_mailbox.message_received event. Carries identifiers, threading, authentication results, and the extracted text — enough for an agent to act without a fetch. Fetch original source (while within its 30-day window) via the thread-member endpoints.
|
|
624
623
|
*/
|
|
625
624
|
type EventEmailMailboxMessageReceivedData = {
|
|
626
625
|
/**
|
|
@@ -651,10 +650,6 @@ type EventEmailMailboxMessageReceivedData = {
|
|
|
651
650
|
* Subject line as received, or null when the message had no subject.
|
|
652
651
|
*/
|
|
653
652
|
subject: string | null;
|
|
654
|
-
/**
|
|
655
|
-
* Where the message landed after receive policy, rules, and scanning were applied.
|
|
656
|
-
*/
|
|
657
|
-
disposition: "inbox" | "blocked" | "unauthenticated";
|
|
658
653
|
/**
|
|
659
654
|
* Plain-text body with quoted history stripped, capped at 64 KB (see truncated_text). Null when extraction produced nothing. This copy is what the mailbox durably retains.
|
|
660
655
|
*/
|
|
@@ -680,22 +675,9 @@ type EventEmailMailboxMessageReceivedData = {
|
|
|
680
675
|
*/
|
|
681
676
|
dmarc_pass?: boolean | null;
|
|
682
677
|
};
|
|
678
|
+
type InboundEmailMessageId = string;
|
|
683
679
|
/**
|
|
684
|
-
* An email
|
|
685
|
-
*/
|
|
686
|
-
type EventEmailMailboxMessageReceivedBlocked = {
|
|
687
|
-
/**
|
|
688
|
-
* Event type.
|
|
689
|
-
*/
|
|
690
|
-
type: "email_mailbox.message_received_blocked";
|
|
691
|
-
/**
|
|
692
|
-
* When the event occurred.
|
|
693
|
-
*/
|
|
694
|
-
timestamp: string;
|
|
695
|
-
data: EventEmailMailboxMessageReceivedData;
|
|
696
|
-
};
|
|
697
|
-
/**
|
|
698
|
-
* An email was received into a mailbox, threaded, and stored with disposition inbox. The payload carries identifiers, threading, authentication results, and the extracted text — enough for an agent to act without a fetch. Dual-fire rule: mailbox-owned inbound with disposition inbox ALSO fires the unchanged email.received event; the streams are unordered relative to each other, so pick one family per automation and dedupe by message_id.
|
|
680
|
+
* An email arrived in a mailbox and was filed to its inbox, threaded and stored. The payload carries identifiers, threading, authentication results, and the extracted text — enough for an agent to act without a fetch. Dual-fire rule: the same message ALSO fires the unchanged email.received event; the streams are unordered relative to each other, so pick one family per automation and dedupe by message_id.
|
|
699
681
|
*/
|
|
700
682
|
type EventEmailMailboxMessageReceived = {
|
|
701
683
|
/**
|
|
@@ -1339,10 +1321,6 @@ type WebhookEvent = ({
|
|
|
1339
1321
|
} & EventEmailMailboxMessageFailed) | ({
|
|
1340
1322
|
type: "email_mailbox.message_received";
|
|
1341
1323
|
} & EventEmailMailboxMessageReceived) | ({
|
|
1342
|
-
type: "email_mailbox.message_received_blocked";
|
|
1343
|
-
} & EventEmailMailboxMessageReceivedBlocked) | ({
|
|
1344
|
-
type: "email_mailbox.message_received_unauthenticated";
|
|
1345
|
-
} & EventEmailMailboxMessageReceivedUnauthenticated) | ({
|
|
1346
1324
|
type: "email_mailbox.message_sent";
|
|
1347
1325
|
} & EventEmailMailboxMessageSent) | ({
|
|
1348
1326
|
type: "email_mailbox.suspended";
|
|
@@ -1369,40 +1347,6 @@ type Timestamps = {
|
|
|
1369
1347
|
readonly created_at: string;
|
|
1370
1348
|
readonly updated_at: string;
|
|
1371
1349
|
};
|
|
1372
|
-
/**
|
|
1373
|
-
* File attached to an email send. The attachment bytes are passed as base64-encoded `content` directly in the request body (required). The `path` field (provide a URL and Bird fetches the attachment for you) is a preview feature and currently unavailable. Requests are rejected with 422 if `content` is missing — `path` alone does not satisfy the schema. When `path` becomes generally available, the schema will be relaxed so that exactly one of `content` or `path` is required.
|
|
1374
|
-
* Inline images for `<img src="cid:..."/>` references in the HTML body use the `content_id` field together with `content`.
|
|
1375
|
-
* Bird enforces a **20 MB estimated generated message size** cap. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. This is not a raw file-size cap. As a rule of thumb, keep total raw attachment content at or below **15 MB** so the generated message has enough room after encoding and MIME wrapping.
|
|
1376
|
-
* Recipient-side delivery reality: downstream limits vary by product and tenant/server policy. Gmail personal and Outlook.com document 25 MB attachment limits. Exchange Online defaults to 35 MB send / 36 MB receive, but admins can configure limits; on-prem Exchange Server organizational defaults are 10 MB. Sends close to Bird's 20 MB generated-message cap may be accepted by Bird but bounce at the recipient's mail server.
|
|
1377
|
-
* Batch sends can include attachments on individual message objects. Each message still has the 20 MB estimated generated-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap. Certain executable / script content types are rejected at validation time.
|
|
1378
|
-
*
|
|
1379
|
-
*/
|
|
1380
|
-
type EmailAttachment = {
|
|
1381
|
-
/**
|
|
1382
|
-
* Filename shown to the recipient. Required.
|
|
1383
|
-
*/
|
|
1384
|
-
filename: string;
|
|
1385
|
-
/**
|
|
1386
|
-
* Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
|
|
1387
|
-
*
|
|
1388
|
-
*/
|
|
1389
|
-
content: string;
|
|
1390
|
-
/**
|
|
1391
|
-
* Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use `content` instead. The schema currently requires `content`, so a request with only `path` is rejected with 422 for missing `content`; a request supplying both `content` and `path` is rejected with 422 `unsupported_feature` until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
|
|
1392
|
-
*
|
|
1393
|
-
*/
|
|
1394
|
-
path?: string;
|
|
1395
|
-
/**
|
|
1396
|
-
* MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
|
|
1397
|
-
*
|
|
1398
|
-
*/
|
|
1399
|
-
content_type?: string;
|
|
1400
|
-
/**
|
|
1401
|
-
* RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as `<img src="cid:{content_id}"/>`. When omitted, the attachment is rendered as a regular file attachment.
|
|
1402
|
-
*
|
|
1403
|
-
*/
|
|
1404
|
-
content_id?: string;
|
|
1405
|
-
};
|
|
1406
1350
|
/**
|
|
1407
1351
|
* An email address with an optional display name.
|
|
1408
1352
|
*/
|
|
@@ -1416,260 +1360,285 @@ type EmailAddress = {
|
|
|
1416
1360
|
*/
|
|
1417
1361
|
name?: string;
|
|
1418
1362
|
};
|
|
1419
|
-
|
|
1420
|
-
* A sender or recipient address. Accepts a plain email string (`jane@example.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@example.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request; responses always return the object form.
|
|
1421
|
-
*
|
|
1422
|
-
*/
|
|
1423
|
-
type EmailAddressInput = string | EmailAddress;
|
|
1424
|
-
type ContactId = string;
|
|
1425
|
-
type EmailTemplateVersionList = {
|
|
1363
|
+
type WhatsAppTemplateList = {
|
|
1426
1364
|
/**
|
|
1427
|
-
*
|
|
1365
|
+
* The templates available to your workspace.
|
|
1428
1366
|
*/
|
|
1429
|
-
data: Array<
|
|
1367
|
+
data: Array<WhatsAppTemplate>;
|
|
1430
1368
|
};
|
|
1431
|
-
|
|
1432
|
-
* A single variable slot a template fills in from the values supplied when sending. Shared across channels (SMS, email) so template introspection reads the same everywhere.
|
|
1433
|
-
*
|
|
1434
|
-
*/
|
|
1435
|
-
type TemplateVariable = {
|
|
1436
|
-
/**
|
|
1437
|
-
* The parameters key this slot is filled with.
|
|
1438
|
-
*/
|
|
1439
|
-
readonly key: string;
|
|
1369
|
+
type WhatsAppTemplateButton = {
|
|
1440
1370
|
/**
|
|
1441
|
-
* The
|
|
1442
|
-
*
|
|
1371
|
+
* The button's behavior type.
|
|
1443
1372
|
*/
|
|
1444
1373
|
readonly type: string;
|
|
1445
1374
|
/**
|
|
1446
|
-
*
|
|
1447
|
-
*
|
|
1448
|
-
*/
|
|
1449
|
-
readonly required: boolean;
|
|
1450
|
-
/**
|
|
1451
|
-
* A human-readable description of the accepted values.
|
|
1375
|
+
* The button's label text.
|
|
1452
1376
|
*/
|
|
1453
|
-
readonly
|
|
1454
|
-
};
|
|
1455
|
-
type EmailTemplateId = string;
|
|
1456
|
-
type EmailTemplateVersionId = string;
|
|
1457
|
-
type EmailTemplateVersion = {
|
|
1377
|
+
readonly text: string;
|
|
1458
1378
|
/**
|
|
1459
|
-
*
|
|
1379
|
+
* The URL the button opens, with any variable placeholder shown inline. Present on link buttons.
|
|
1460
1380
|
*/
|
|
1461
|
-
readonly
|
|
1381
|
+
readonly url?: string;
|
|
1462
1382
|
/**
|
|
1463
|
-
*
|
|
1383
|
+
* Example values for this button's variables, in placeholder order. Present when the button URL has variables.
|
|
1464
1384
|
*/
|
|
1465
|
-
readonly
|
|
1385
|
+
readonly example_parameters?: Array<WhatsAppTemplateExampleParameter>;
|
|
1386
|
+
};
|
|
1387
|
+
/**
|
|
1388
|
+
* The type of a template parameter.
|
|
1389
|
+
*/
|
|
1390
|
+
type WhatsAppTemplateParameterType = string;
|
|
1391
|
+
type WhatsAppTemplateExampleParameter = {
|
|
1466
1392
|
/**
|
|
1467
|
-
*
|
|
1393
|
+
* The kind of value this parameter accepts.
|
|
1468
1394
|
*/
|
|
1469
|
-
readonly
|
|
1395
|
+
readonly type: WhatsAppTemplateParameterType;
|
|
1470
1396
|
/**
|
|
1471
|
-
*
|
|
1397
|
+
* An example value for a text parameter. Present when `type` is `text`.
|
|
1472
1398
|
*/
|
|
1473
|
-
readonly
|
|
1399
|
+
readonly text?: string;
|
|
1400
|
+
};
|
|
1401
|
+
type WhatsAppTemplateComponent = {
|
|
1474
1402
|
/**
|
|
1475
|
-
* The
|
|
1403
|
+
* The content block's type within the template.
|
|
1476
1404
|
*/
|
|
1477
|
-
readonly
|
|
1405
|
+
readonly type: string;
|
|
1478
1406
|
/**
|
|
1479
|
-
* The
|
|
1407
|
+
* The block's text content, with any variable placeholders shown inline. Present when the block carries text.
|
|
1480
1408
|
*/
|
|
1481
|
-
readonly
|
|
1409
|
+
readonly text?: string;
|
|
1482
1410
|
/**
|
|
1483
|
-
*
|
|
1411
|
+
* Example values for this block's variables, in placeholder order — one per `{{n}}`. Use them to see what a filled message looks like. Present when the block has variables.
|
|
1484
1412
|
*/
|
|
1485
|
-
readonly
|
|
1413
|
+
readonly example_parameters?: Array<WhatsAppTemplateExampleParameter>;
|
|
1486
1414
|
/**
|
|
1487
|
-
*
|
|
1415
|
+
* The buttons attached to this block. Present when the block carries buttons.
|
|
1488
1416
|
*/
|
|
1489
|
-
readonly
|
|
1417
|
+
readonly buttons?: Array<WhatsAppTemplateButton>;
|
|
1490
1418
|
};
|
|
1491
1419
|
/**
|
|
1492
|
-
*
|
|
1420
|
+
* A message template's review and health status. `approved`, `pending`, and `rejected` are review outcomes; `paused`, `disabled`, `in_appeal`, `pending_deletion`, and `limit_exceeded` reflect a template's ongoing health after approval.
|
|
1421
|
+
*/
|
|
1422
|
+
type WhatsAppTemplateStatus = string;
|
|
1423
|
+
/**
|
|
1424
|
+
* WhatsApp template category — Meta's content classification for a template. Open enum — Meta may add new categories over time, so treat any unrecognized value as a future category rather than an error. The values below are the categories known at this version.
|
|
1425
|
+
*/
|
|
1426
|
+
type WhatsAppTemplateCategory = string;
|
|
1427
|
+
/**
|
|
1428
|
+
* Whether the template is a built-in Bird template (`system`) or one your workspace authored (`workspace`).
|
|
1429
|
+
*/
|
|
1430
|
+
type TemplateScope = "system" | "workspace";
|
|
1431
|
+
/**
|
|
1432
|
+
* A template's send-by handle — the stable reference used in place of the template id when sending. Lowercase letters, numbers, hyphens, and underscores; starts and ends with a letter or number.
|
|
1493
1433
|
*
|
|
1494
1434
|
*/
|
|
1495
|
-
type
|
|
1435
|
+
type TemplateName = string;
|
|
1436
|
+
type WhatsAppTemplate = {
|
|
1496
1437
|
/**
|
|
1497
|
-
* The
|
|
1498
|
-
*
|
|
1438
|
+
* The template's stable handle. Pass it as the template reference when sending.
|
|
1499
1439
|
*/
|
|
1500
|
-
|
|
1440
|
+
readonly name: TemplateName;
|
|
1441
|
+
scope: TemplateScope;
|
|
1501
1442
|
/**
|
|
1502
|
-
*
|
|
1503
|
-
*
|
|
1443
|
+
* The language code of this template variant (for example `en` or `pt_BR`).
|
|
1504
1444
|
*/
|
|
1505
|
-
|
|
1445
|
+
readonly language: string;
|
|
1506
1446
|
/**
|
|
1507
|
-
*
|
|
1447
|
+
* Content classification applied to messages sent from this template.
|
|
1508
1448
|
*/
|
|
1509
|
-
|
|
1449
|
+
readonly category: WhatsAppTemplateCategory;
|
|
1510
1450
|
/**
|
|
1511
|
-
*
|
|
1451
|
+
* The template's review and health status.
|
|
1512
1452
|
*/
|
|
1513
|
-
|
|
1453
|
+
readonly status: WhatsAppTemplateStatus;
|
|
1514
1454
|
/**
|
|
1515
|
-
*
|
|
1455
|
+
* The content blocks that make up the template, in display order.
|
|
1516
1456
|
*/
|
|
1517
|
-
|
|
1457
|
+
readonly components: Array<WhatsAppTemplateComponent>;
|
|
1458
|
+
};
|
|
1459
|
+
type WhatsAppEventList = {
|
|
1518
1460
|
/**
|
|
1519
|
-
*
|
|
1461
|
+
* Timeline events for this WhatsApp message, in chronological order. The timeline is bounded and returned in full — this list is not paginated.
|
|
1520
1462
|
*/
|
|
1521
|
-
|
|
1463
|
+
data: Array<WhatsAppEvent>;
|
|
1464
|
+
};
|
|
1465
|
+
/**
|
|
1466
|
+
* Bird-stable failure reason, uniform whether the failure happened internally or was reported by the WhatsApp network. `insufficient_balance` — the workspace could not afford the send. `price_not_found` — no price was configured for this destination/template combination. `internal_error` — an unexpected Bird-side failure. `undeliverable` — the recipient could not be reached (e.g. not on WhatsApp, number invalid). `service_window_expired` — the 24-hour customer care window has closed and a free-form message cannot be sent; send a template instead. `rate_limited` — the send was throttled.
|
|
1467
|
+
*
|
|
1468
|
+
*/
|
|
1469
|
+
type WhatsAppErrorCode = string;
|
|
1470
|
+
/**
|
|
1471
|
+
* Failure detail for a message that could not be delivered. Null when there is no failure.
|
|
1472
|
+
*/
|
|
1473
|
+
type WhatsAppError = {
|
|
1474
|
+
code: WhatsAppErrorCode;
|
|
1522
1475
|
/**
|
|
1523
|
-
*
|
|
1476
|
+
* Human-readable explanation of the failure.
|
|
1524
1477
|
*/
|
|
1525
|
-
|
|
1526
|
-
};
|
|
1527
|
-
type BrandKitId = string;
|
|
1528
|
-
type EmailTemplate = {
|
|
1478
|
+
readonly description: string;
|
|
1529
1479
|
/**
|
|
1530
|
-
*
|
|
1480
|
+
* When the failure occurred.
|
|
1531
1481
|
*/
|
|
1532
|
-
readonly
|
|
1482
|
+
readonly occurred_at: string;
|
|
1483
|
+
} | null;
|
|
1484
|
+
type WhatsAppEventId = string;
|
|
1485
|
+
type WhatsAppEvent = {
|
|
1533
1486
|
/**
|
|
1534
|
-
*
|
|
1487
|
+
* Event ID.
|
|
1535
1488
|
*/
|
|
1536
|
-
readonly
|
|
1489
|
+
readonly id: WhatsAppEventId;
|
|
1537
1490
|
/**
|
|
1538
|
-
*
|
|
1491
|
+
* Lifecycle event type. `whatsapp.accepted` — Bird accepted the request. `whatsapp.sent` — handed to the WhatsApp network. `whatsapp.delivered` — delivery confirmed to the recipient's device. `whatsapp.read` — the recipient opened the message (this does not change the message `status`, which never becomes `read`). `whatsapp.failed` — terminal permanent failure. Open enum — new event types may be added over time, so treat any unrecognized value as a future event rather than an error.
|
|
1492
|
+
*
|
|
1539
1493
|
*/
|
|
1540
|
-
|
|
1494
|
+
readonly type: string;
|
|
1541
1495
|
/**
|
|
1542
|
-
*
|
|
1496
|
+
* When this event occurred.
|
|
1543
1497
|
*/
|
|
1544
|
-
|
|
1545
|
-
scope: TemplateScope;
|
|
1546
|
-
category: EmailTemplateCategory;
|
|
1547
|
-
source: EmailTemplateSource;
|
|
1498
|
+
readonly occurred_at: string;
|
|
1548
1499
|
/**
|
|
1549
|
-
*
|
|
1500
|
+
* Failure detail. Present on `whatsapp.failed` events; null otherwise.
|
|
1550
1501
|
*/
|
|
1551
|
-
|
|
1502
|
+
error: WhatsAppError;
|
|
1503
|
+
};
|
|
1504
|
+
type SendWhatsAppMessageRequest = {
|
|
1552
1505
|
/**
|
|
1553
|
-
* The
|
|
1506
|
+
* The message recipient's phone number in E.164 format (for example `+31612345678`).
|
|
1554
1507
|
*/
|
|
1555
|
-
|
|
1508
|
+
to: string;
|
|
1556
1509
|
/**
|
|
1557
|
-
* The
|
|
1510
|
+
* The template to send. Bird selects the sender number from the template's category, so there is no sender field on this request. Templates are currently the only supported content type, so every send must include one; free-text content will be added in a future release.
|
|
1511
|
+
*
|
|
1558
1512
|
*/
|
|
1559
|
-
|
|
1513
|
+
template?: SendWhatsAppMessageTemplate;
|
|
1514
|
+
};
|
|
1515
|
+
type WhatsAppMessageTemplateComponentParameter = {
|
|
1560
1516
|
/**
|
|
1561
|
-
*
|
|
1517
|
+
* Parameter type.
|
|
1562
1518
|
*/
|
|
1563
|
-
|
|
1519
|
+
type: WhatsAppTemplateParameterType;
|
|
1564
1520
|
/**
|
|
1565
|
-
*
|
|
1521
|
+
* Parameter value.
|
|
1566
1522
|
*/
|
|
1567
|
-
|
|
1523
|
+
text: string;
|
|
1524
|
+
};
|
|
1525
|
+
type WhatsAppMessageTemplateComponent = {
|
|
1568
1526
|
/**
|
|
1569
|
-
*
|
|
1527
|
+
* Which part of the template this fills in.
|
|
1570
1528
|
*/
|
|
1571
|
-
|
|
1529
|
+
type: string;
|
|
1572
1530
|
/**
|
|
1573
|
-
* The
|
|
1531
|
+
* The values that fill this part's placeholders, in order.
|
|
1574
1532
|
*/
|
|
1575
|
-
|
|
1533
|
+
parameters?: Array<WhatsAppMessageTemplateComponentParameter>;
|
|
1534
|
+
};
|
|
1535
|
+
type SendWhatsAppMessageTemplate = {
|
|
1576
1536
|
/**
|
|
1577
|
-
* The
|
|
1537
|
+
* The template to send, by its name (for example `bird_otp`).
|
|
1578
1538
|
*/
|
|
1579
|
-
|
|
1539
|
+
name: TemplateName;
|
|
1580
1540
|
/**
|
|
1581
|
-
*
|
|
1541
|
+
* Language code of the template variant to send (for example `en` or `pt_BR`). May be omitted when the template has a single language.
|
|
1542
|
+
*
|
|
1582
1543
|
*/
|
|
1583
|
-
|
|
1544
|
+
language?: string;
|
|
1584
1545
|
/**
|
|
1585
|
-
*
|
|
1546
|
+
* The values that fill the template's placeholders.
|
|
1586
1547
|
*/
|
|
1587
|
-
|
|
1548
|
+
components?: Array<WhatsAppMessageTemplateComponent>;
|
|
1588
1549
|
};
|
|
1589
1550
|
/**
|
|
1590
|
-
*
|
|
1591
|
-
|
|
1592
|
-
type EmailTemplateSource = "liquid" | "handlebars" | "html";
|
|
1593
|
-
/**
|
|
1594
|
-
* Whether the template is transactional or marketing email.
|
|
1595
|
-
*/
|
|
1596
|
-
type EmailTemplateCategory = "transactional" | "marketing";
|
|
1597
|
-
/**
|
|
1598
|
-
* Whether the template is a built-in Bird template (`system`) or one your workspace authored (`workspace`).
|
|
1551
|
+
* Delivery status. `scheduled` means the message is queued to send at a future time and has not been dispatched yet. `accepted` means Bird accepted the request and it is queued for sending. `sent` means it was handed to the WhatsApp network. `delivered` is confirmed delivery to the recipient's device. `failed` is a terminal permanent failure. `canceled` means a scheduled message was canceled before it was sent. `received` is the status of an inbound message (`direction: inbound`) sent to you by a contact. There is no `read` status — a read receipt is reported as `read_at` and a `whatsapp.read` event, not a status value.
|
|
1552
|
+
*
|
|
1599
1553
|
*/
|
|
1600
|
-
type
|
|
1554
|
+
type WhatsAppMessageStatus = "scheduled" | "accepted" | "sent" | "delivered" | "failed" | "canceled" | "received";
|
|
1601
1555
|
/**
|
|
1602
|
-
*
|
|
1556
|
+
* The template a message was sent from. On reads `name`, `language`, `category`, and `components` are always present — `components` is an empty array for an authentication template (the filled-in values, e.g. a verification code, are never returned).
|
|
1557
|
+
*
|
|
1603
1558
|
*/
|
|
1604
|
-
type
|
|
1559
|
+
type WhatsAppMessageTemplate = {
|
|
1605
1560
|
/**
|
|
1606
|
-
* The template's
|
|
1607
|
-
*
|
|
1561
|
+
* The template's stable handle (for example `bird_otp`).
|
|
1608
1562
|
*/
|
|
1609
|
-
name:
|
|
1563
|
+
readonly name: TemplateName;
|
|
1610
1564
|
/**
|
|
1611
|
-
*
|
|
1565
|
+
* Content classification applied to messages sent from this template.
|
|
1612
1566
|
*/
|
|
1613
|
-
|
|
1614
|
-
|
|
1567
|
+
readonly category: WhatsAppTemplateCategory;
|
|
1568
|
+
/**
|
|
1569
|
+
* The language code of the template variant that was sent (for example `en`).
|
|
1570
|
+
*/
|
|
1571
|
+
readonly language: string;
|
|
1615
1572
|
/**
|
|
1616
|
-
* The
|
|
1573
|
+
* The values that filled the template's placeholders. Empty for an authentication template, whose content is never returned.
|
|
1617
1574
|
*
|
|
1618
1575
|
*/
|
|
1619
|
-
|
|
1576
|
+
readonly components: Array<WhatsAppMessageTemplateComponent>;
|
|
1577
|
+
};
|
|
1578
|
+
/**
|
|
1579
|
+
* Contact on the other end of the message. Fields are omitted when not available; at least one is always present.
|
|
1580
|
+
*/
|
|
1581
|
+
type WhatsAppMessageContact = {
|
|
1620
1582
|
/**
|
|
1621
|
-
*
|
|
1583
|
+
* Contact's phone number in E.164 format, when known.
|
|
1622
1584
|
*/
|
|
1623
|
-
|
|
1585
|
+
readonly phone_number?: string;
|
|
1624
1586
|
/**
|
|
1625
|
-
*
|
|
1587
|
+
* Business-scoped user ID (Meta's WhatsApp identifier for this contact within the business account), when available.
|
|
1626
1588
|
*/
|
|
1627
|
-
|
|
1589
|
+
readonly bsuid?: string;
|
|
1590
|
+
};
|
|
1591
|
+
/**
|
|
1592
|
+
* The business identity that sent the message. `phone_number` is always present; `phone_number_id` is included only for account-owned numbers.
|
|
1593
|
+
*
|
|
1594
|
+
*/
|
|
1595
|
+
type WhatsAppMessageBusiness = {
|
|
1628
1596
|
/**
|
|
1629
|
-
*
|
|
1597
|
+
* E.164 phone number of the WhatsApp business account that sent the message.
|
|
1630
1598
|
*/
|
|
1631
|
-
|
|
1599
|
+
readonly phone_number?: string;
|
|
1632
1600
|
/**
|
|
1633
|
-
*
|
|
1601
|
+
* The WhatsApp phone number identifier. Present only for account-owned numbers.
|
|
1634
1602
|
*/
|
|
1635
|
-
|
|
1603
|
+
readonly phone_number_id?: string;
|
|
1636
1604
|
};
|
|
1637
|
-
type
|
|
1605
|
+
type WhatsAppMessageId = string;
|
|
1606
|
+
type WhatsAppMessage = {
|
|
1638
1607
|
/**
|
|
1639
|
-
*
|
|
1608
|
+
* Message ID.
|
|
1640
1609
|
*/
|
|
1641
|
-
readonly id:
|
|
1610
|
+
readonly id: WhatsAppMessageId;
|
|
1642
1611
|
/**
|
|
1643
|
-
*
|
|
1612
|
+
* Whether the message was sent by the business (`outbound`) or received from the contact (`inbound`).
|
|
1644
1613
|
*/
|
|
1645
|
-
readonly
|
|
1614
|
+
readonly direction: "outbound" | "inbound";
|
|
1615
|
+
readonly business: WhatsAppMessageBusiness;
|
|
1616
|
+
readonly contact: WhatsAppMessageContact;
|
|
1646
1617
|
/**
|
|
1647
|
-
* The template
|
|
1618
|
+
* The template the message was sent from. For authentication templates the filled-in values are not returned.
|
|
1648
1619
|
*/
|
|
1649
|
-
|
|
1620
|
+
readonly template?: WhatsAppMessageTemplate;
|
|
1621
|
+
readonly status: WhatsAppMessageStatus;
|
|
1650
1622
|
/**
|
|
1651
|
-
*
|
|
1623
|
+
* Failure detail for a message that did not reach the recipient. Null when there is no failure.
|
|
1652
1624
|
*/
|
|
1653
|
-
|
|
1654
|
-
scope: TemplateScope;
|
|
1655
|
-
category: EmailTemplateCategory;
|
|
1656
|
-
source: EmailTemplateSource;
|
|
1625
|
+
last_error?: WhatsAppError;
|
|
1657
1626
|
/**
|
|
1658
|
-
*
|
|
1627
|
+
* When the message was accepted for delivery.
|
|
1659
1628
|
*/
|
|
1660
|
-
readonly
|
|
1629
|
+
readonly created_at: string;
|
|
1661
1630
|
/**
|
|
1662
|
-
*
|
|
1631
|
+
* When the message was handed to the WhatsApp network. Null until then.
|
|
1663
1632
|
*/
|
|
1664
|
-
readonly
|
|
1633
|
+
readonly sent_at?: string | null;
|
|
1665
1634
|
/**
|
|
1666
|
-
* When
|
|
1635
|
+
* When delivery was confirmed. Null until then.
|
|
1667
1636
|
*/
|
|
1668
|
-
readonly
|
|
1637
|
+
readonly delivered_at?: string | null;
|
|
1669
1638
|
/**
|
|
1670
|
-
* When the
|
|
1639
|
+
* When the message was read by the recipient. Null until then.
|
|
1671
1640
|
*/
|
|
1672
|
-
readonly
|
|
1641
|
+
readonly read_at?: string | null;
|
|
1673
1642
|
};
|
|
1674
1643
|
type SmsTemplateList = {
|
|
1675
1644
|
/**
|
|
@@ -1678,6 +1647,30 @@ type SmsTemplateList = {
|
|
|
1678
1647
|
data: Array<SmsTemplate>;
|
|
1679
1648
|
};
|
|
1680
1649
|
type SmsTemplateVersionId = string;
|
|
1650
|
+
/**
|
|
1651
|
+
* A single variable slot a template fills in from the values supplied when sending. Shared across channels (SMS, email) so template introspection reads the same everywhere.
|
|
1652
|
+
*
|
|
1653
|
+
*/
|
|
1654
|
+
type TemplateVariable = {
|
|
1655
|
+
/**
|
|
1656
|
+
* The parameters key this slot is filled with.
|
|
1657
|
+
*/
|
|
1658
|
+
readonly key: string;
|
|
1659
|
+
/**
|
|
1660
|
+
* The value type this slot accepts. Open enum — treat any unrecognized value as a future type rather than an error. SMS templates use the typed slots (`code`, `amount`, …); email templates use `text`.
|
|
1661
|
+
*
|
|
1662
|
+
*/
|
|
1663
|
+
readonly type: string;
|
|
1664
|
+
/**
|
|
1665
|
+
* Whether the slot must be supplied when sending. Advisory for email templates, where a missing value renders as empty rather than rejecting the send.
|
|
1666
|
+
*
|
|
1667
|
+
*/
|
|
1668
|
+
readonly required: boolean;
|
|
1669
|
+
/**
|
|
1670
|
+
* A human-readable description of the accepted values.
|
|
1671
|
+
*/
|
|
1672
|
+
readonly constraint: string;
|
|
1673
|
+
};
|
|
1681
1674
|
/**
|
|
1682
1675
|
* Content classification. Drives opt-out (STOP) policy, quiet-hours, and per-country compliance.
|
|
1683
1676
|
*/
|
|
@@ -1691,7 +1684,7 @@ type SmsTemplate = {
|
|
|
1691
1684
|
/**
|
|
1692
1685
|
* The template's stable handle. Pass it (or the id) as the template reference when sending.
|
|
1693
1686
|
*/
|
|
1694
|
-
readonly name:
|
|
1687
|
+
readonly name: TemplateName;
|
|
1695
1688
|
/**
|
|
1696
1689
|
* Human-readable description of what the template is for.
|
|
1697
1690
|
*/
|
|
@@ -1908,7 +1901,7 @@ type SmsTemplateSend = unknown & {
|
|
|
1908
1901
|
* The template to send, by its name handle (for example `bird_otp_verification`). Browse the available templates and their variables with the templates endpoint.
|
|
1909
1902
|
*
|
|
1910
1903
|
*/
|
|
1911
|
-
name?:
|
|
1904
|
+
name?: TemplateName;
|
|
1912
1905
|
/**
|
|
1913
1906
|
* Language tag (BCP 47, for example `fr` or `pt-BR`) selecting the localized body. Falls back to the closest available language, then English, when the exact tag is not stocked. Omit for English.
|
|
1914
1907
|
*
|
|
@@ -2017,6 +2010,7 @@ type AudienceContactsRemoveRequest = {
|
|
|
2017
2010
|
*/
|
|
2018
2011
|
contact_ids: Array<ContactId>;
|
|
2019
2012
|
};
|
|
2013
|
+
type ContactId = string;
|
|
2020
2014
|
type AudienceContactsAddRequest = {
|
|
2021
2015
|
/**
|
|
2022
2016
|
* Contacts to add to the audience. Adding a contact that is already a member has no effect. If any ID does not exist, the whole request fails and no contacts are added.
|
|
@@ -2084,26 +2078,6 @@ type AudienceCreateRequest = {
|
|
|
2084
2078
|
*/
|
|
2085
2079
|
type?: "static" | "dynamic" | "external";
|
|
2086
2080
|
};
|
|
2087
|
-
type AudienceId = string;
|
|
2088
|
-
type Audience = {
|
|
2089
|
-
/**
|
|
2090
|
-
* Audience ID.
|
|
2091
|
-
*/
|
|
2092
|
-
readonly id: AudienceId;
|
|
2093
|
-
/**
|
|
2094
|
-
* Display name for the audience.
|
|
2095
|
-
*/
|
|
2096
|
-
name: string;
|
|
2097
|
-
/**
|
|
2098
|
-
* Longer description of who this audience is.
|
|
2099
|
-
*/
|
|
2100
|
-
description?: string | null;
|
|
2101
|
-
/**
|
|
2102
|
-
* How the audience's recipients are determined. `static` audiences have an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable — creating an audience with either returns an error.
|
|
2103
|
-
*
|
|
2104
|
-
*/
|
|
2105
|
-
type: "static" | "dynamic" | "external";
|
|
2106
|
-
} & Timestamps;
|
|
2107
2081
|
type ContactPropertyUpdateRequest = {
|
|
2108
2082
|
/**
|
|
2109
2083
|
* Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, or boolean matching the declared type (strings up to 500 characters). Set to null to remove the fallback.
|
|
@@ -2147,6 +2121,26 @@ type ContactProperty = {
|
|
|
2147
2121
|
*/
|
|
2148
2122
|
readonly archived?: boolean;
|
|
2149
2123
|
} & Timestamps;
|
|
2124
|
+
type AudienceId = string;
|
|
2125
|
+
type Audience = {
|
|
2126
|
+
/**
|
|
2127
|
+
* Audience ID.
|
|
2128
|
+
*/
|
|
2129
|
+
readonly id: AudienceId;
|
|
2130
|
+
/**
|
|
2131
|
+
* Display name for the audience.
|
|
2132
|
+
*/
|
|
2133
|
+
name: string;
|
|
2134
|
+
/**
|
|
2135
|
+
* Longer description of who this audience is.
|
|
2136
|
+
*/
|
|
2137
|
+
description?: string | null;
|
|
2138
|
+
/**
|
|
2139
|
+
* How the audience's recipients are determined. `static` audiences have an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable — creating an audience with either returns an error.
|
|
2140
|
+
*
|
|
2141
|
+
*/
|
|
2142
|
+
type: "static" | "dynamic" | "external";
|
|
2143
|
+
} & Timestamps;
|
|
2150
2144
|
type ContactUpdateRequest = {
|
|
2151
2145
|
/**
|
|
2152
2146
|
* New email address for the contact. Trimmed and lowercased before it is stored and checked for uniqueness. Must not be in use by another contact in the workspace.
|
|
@@ -2271,6 +2265,41 @@ type EmailMessageBatchItem = {
|
|
|
2271
2265
|
*
|
|
2272
2266
|
*/
|
|
2273
2267
|
type EmailMessageBatchRequest = Array<EmailMessageSendRequest>;
|
|
2268
|
+
/**
|
|
2269
|
+
* File attached to an email send. The attachment bytes are passed as base64-encoded `content` directly in the request body (required). The `path` field (provide a URL and Bird fetches the attachment for you) is a preview feature and currently unavailable. Requests are rejected with 422 if `content` is missing — `path` alone does not satisfy the schema. When `path` becomes generally available, the schema will be relaxed so that exactly one of `content` or `path` is required.
|
|
2270
|
+
* Inline images for `<img src="cid:..."/>` references in the HTML body use the `content_id` field together with `content`.
|
|
2271
|
+
* Bird enforces a **20 MB estimated generated message size** cap. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. This is not a raw file-size cap. As a rule of thumb, keep total raw attachment content at or below **15 MB** so the generated message has enough room after encoding and MIME wrapping.
|
|
2272
|
+
* Recipient-side delivery reality: downstream limits vary by product and tenant/server policy. Gmail personal and Outlook.com document 25 MB attachment limits. Exchange Online defaults to 35 MB send / 36 MB receive, but admins can configure limits; on-prem Exchange Server organizational defaults are 10 MB. Sends close to Bird's 20 MB generated-message cap may be accepted by Bird but bounce at the recipient's mail server.
|
|
2273
|
+
* Batch sends can include attachments on individual message objects. Each message still has the 20 MB estimated generated-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap. Certain executable / script content types are rejected at validation time.
|
|
2274
|
+
*
|
|
2275
|
+
*/
|
|
2276
|
+
type EmailAttachment = {
|
|
2277
|
+
/**
|
|
2278
|
+
* Filename shown to the recipient. Required.
|
|
2279
|
+
*/
|
|
2280
|
+
filename: string;
|
|
2281
|
+
/**
|
|
2282
|
+
* Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
|
|
2283
|
+
*
|
|
2284
|
+
*/
|
|
2285
|
+
content: string;
|
|
2286
|
+
/**
|
|
2287
|
+
* Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use `content` instead. The schema currently requires `content`, so a request with only `path` is rejected with 422 for missing `content`; a request supplying both `content` and `path` is rejected with 422 `unsupported_feature` until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
|
|
2288
|
+
*
|
|
2289
|
+
*/
|
|
2290
|
+
path?: string;
|
|
2291
|
+
/**
|
|
2292
|
+
* MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
|
|
2293
|
+
*
|
|
2294
|
+
*/
|
|
2295
|
+
content_type?: string;
|
|
2296
|
+
/**
|
|
2297
|
+
* RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as `<img src="cid:{content_id}"/>`. When omitted, the attachment is rendered as a regular file attachment.
|
|
2298
|
+
*
|
|
2299
|
+
*/
|
|
2300
|
+
content_id?: string;
|
|
2301
|
+
};
|
|
2302
|
+
type EmailTemplateId = string;
|
|
2274
2303
|
type EmailTemplateSend = unknown & {
|
|
2275
2304
|
/**
|
|
2276
2305
|
* The template to send, by its id.
|
|
@@ -2279,7 +2308,7 @@ type EmailTemplateSend = unknown & {
|
|
|
2279
2308
|
/**
|
|
2280
2309
|
* The template to send, by its name handle (for example `welcome-email`).
|
|
2281
2310
|
*/
|
|
2282
|
-
name?:
|
|
2311
|
+
name?: TemplateName;
|
|
2283
2312
|
/**
|
|
2284
2313
|
* Values for the template's variables, keyed by variable name. A token with no matching value renders empty. Cap: 16 KB serialized.
|
|
2285
2314
|
*
|
|
@@ -2288,6 +2317,11 @@ type EmailTemplateSend = unknown & {
|
|
|
2288
2317
|
[key: string]: unknown;
|
|
2289
2318
|
};
|
|
2290
2319
|
};
|
|
2320
|
+
/**
|
|
2321
|
+
* A sender or recipient address. Accepts a plain email string (`jane@example.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@example.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request; responses always return the object form.
|
|
2322
|
+
*
|
|
2323
|
+
*/
|
|
2324
|
+
type EmailAddressInput = string | EmailAddress;
|
|
2291
2325
|
type EmailMessageSendRequest = {
|
|
2292
2326
|
/**
|
|
2293
2327
|
* Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name. Must be from a verified domain in this workspace.
|
|
@@ -2381,7 +2415,8 @@ type EmailMessageSendRequest = {
|
|
|
2381
2415
|
*/
|
|
2382
2416
|
attachments?: Array<EmailAttachment>;
|
|
2383
2417
|
/**
|
|
2384
|
-
*
|
|
2418
|
+
* Schedule the message to send at a future time instead of immediately. Must be at least 30 seconds and at most 30 days ahead — outside that range the request is rejected with `422`. The message returns with status `accepted` and shows as `scheduled` on reads until it sends; cancel it before then with the message cancel endpoint. Scheduled sends count against your plan's monthly scheduled-email allowance; exceeding it is rejected with a `422`.
|
|
2419
|
+
*
|
|
2385
2420
|
*/
|
|
2386
2421
|
scheduled_at?: string;
|
|
2387
2422
|
/**
|
|
@@ -2669,6 +2704,10 @@ type ListAudiencesData = {
|
|
|
2669
2704
|
body?: never;
|
|
2670
2705
|
path?: never;
|
|
2671
2706
|
query?: {
|
|
2707
|
+
/**
|
|
2708
|
+
* Case-insensitive substring match against the audience's name.
|
|
2709
|
+
*/
|
|
2710
|
+
search?: string;
|
|
2672
2711
|
/**
|
|
2673
2712
|
* Maximum number of items to return per page.
|
|
2674
2713
|
*/
|
|
@@ -2785,22 +2824,10 @@ type ListSmsTemplatesData = {
|
|
|
2785
2824
|
};
|
|
2786
2825
|
url: "/v1/sms/templates";
|
|
2787
2826
|
};
|
|
2788
|
-
type
|
|
2827
|
+
type ListWhatsAppMessagesData = {
|
|
2789
2828
|
body?: never;
|
|
2790
2829
|
path?: never;
|
|
2791
2830
|
query?: {
|
|
2792
|
-
/**
|
|
2793
|
-
* Filter by template category.
|
|
2794
|
-
*/
|
|
2795
|
-
category?: EmailTemplateCategory;
|
|
2796
|
-
/**
|
|
2797
|
-
* Filter by authoring format.
|
|
2798
|
-
*/
|
|
2799
|
-
source?: EmailTemplateSource;
|
|
2800
|
-
/**
|
|
2801
|
-
* Case-insensitive search matching the template's name or description (substring).
|
|
2802
|
-
*/
|
|
2803
|
-
name?: string;
|
|
2804
2831
|
/**
|
|
2805
2832
|
* Maximum number of items to return per page.
|
|
2806
2833
|
*/
|
|
@@ -2813,8 +2840,44 @@ type ListEmailTemplatesData = {
|
|
|
2813
2840
|
* Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
|
|
2814
2841
|
*/
|
|
2815
2842
|
ending_before?: string;
|
|
2843
|
+
/**
|
|
2844
|
+
* Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
|
|
2845
|
+
*/
|
|
2846
|
+
created_after?: string;
|
|
2847
|
+
/**
|
|
2848
|
+
* Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
|
|
2849
|
+
*/
|
|
2850
|
+
created_before?: string;
|
|
2851
|
+
/**
|
|
2852
|
+
* Filter by status. Repeat the parameter to match any of several statuses.
|
|
2853
|
+
*/
|
|
2854
|
+
status?: Array<WhatsAppMessageStatus>;
|
|
2855
|
+
/**
|
|
2856
|
+
* Filter by contact phone number (E.164 exact match).
|
|
2857
|
+
*/
|
|
2858
|
+
phone_number?: string;
|
|
2859
|
+
/**
|
|
2860
|
+
* Filter by business-scoped user ID (Meta identifier).
|
|
2861
|
+
*/
|
|
2862
|
+
bsuid?: string;
|
|
2863
|
+
};
|
|
2864
|
+
url: "/v1/whatsapp/messages";
|
|
2865
|
+
};
|
|
2866
|
+
type ListWhatsAppMessageEventsData = {
|
|
2867
|
+
body?: never;
|
|
2868
|
+
path: {
|
|
2869
|
+
/**
|
|
2870
|
+
* Message ID.
|
|
2871
|
+
*/
|
|
2872
|
+
message_id: WhatsAppMessageId;
|
|
2873
|
+
};
|
|
2874
|
+
query?: {
|
|
2875
|
+
/**
|
|
2876
|
+
* Filter by event type (e.g. `whatsapp.delivered`, `whatsapp.failed`).
|
|
2877
|
+
*/
|
|
2878
|
+
type?: string;
|
|
2816
2879
|
};
|
|
2817
|
-
url: "/v1/
|
|
2880
|
+
url: "/v1/whatsapp/messages/{message_id}/events";
|
|
2818
2881
|
};
|
|
2819
2882
|
//#endregion
|
|
2820
2883
|
//#region src/generated/core/auth.gen.d.ts
|
|
@@ -3269,6 +3332,16 @@ declare class EmailResource<D extends EmailChannelDefaults | undefined = undefin
|
|
|
3269
3332
|
* msg.bounced_count;
|
|
3270
3333
|
*/
|
|
3271
3334
|
get(messageId: string, options?: RequestOptions): APIPromise<EmailMessage>;
|
|
3335
|
+
/**
|
|
3336
|
+
* Cancel a message scheduled with `scheduled_at` before it sends. Only a
|
|
3337
|
+
* message that is still scheduled can be canceled; one that already started
|
|
3338
|
+
* sending — or was previously canceled — rejects with a conflict error.
|
|
3339
|
+
* Canceling does not return consumed scheduled-send quota.
|
|
3340
|
+
*
|
|
3341
|
+
* @example
|
|
3342
|
+
* await bird.email.cancel("em_abc123");
|
|
3343
|
+
*/
|
|
3344
|
+
cancel(messageId: string, options?: RequestOptions): APIPromise<void>;
|
|
3272
3345
|
/**
|
|
3273
3346
|
* List messages, newest first. `await` resolves the first page; `for await`
|
|
3274
3347
|
* walks every message across all pages.
|
|
@@ -3499,109 +3572,6 @@ declare class ContactsResource extends Resource {
|
|
|
3499
3572
|
batch(params: ContactBatchParams, options?: RequestOptions): APIPromise<ContactUpsertResult>;
|
|
3500
3573
|
}
|
|
3501
3574
|
//#endregion
|
|
3502
|
-
//#region src/resources/emailTemplates.d.ts
|
|
3503
|
-
/** Body for `bird.emailTemplates.create`. */
|
|
3504
|
-
type EmailTemplateCreateParams = EmailTemplateCreate;
|
|
3505
|
-
/** Body for `bird.emailTemplates.update` — a partial patch of the draft. */
|
|
3506
|
-
type EmailTemplateUpdateParams = EmailTemplateUpdate;
|
|
3507
|
-
/** Filters and cursor params for `bird.emailTemplates.list`. */
|
|
3508
|
-
type EmailTemplateListQuery = NonNullable<ListEmailTemplatesData["query"]>;
|
|
3509
|
-
declare class EmailTemplatesResource extends Resource {
|
|
3510
|
-
/**
|
|
3511
|
-
* Create a template and its initial editable draft. Pick the authoring format
|
|
3512
|
-
* with `source` (`liquid`, `handlebars`, or `html`); the name must be unique
|
|
3513
|
-
* in the workspace or the call throws a `BirdConflictError`.
|
|
3514
|
-
*
|
|
3515
|
-
* @example Create a template
|
|
3516
|
-
* const tpl = await bird.emailTemplates.create({
|
|
3517
|
-
* name: "welcome-email",
|
|
3518
|
-
* description: "Welcome",
|
|
3519
|
-
* category: "transactional",
|
|
3520
|
-
* source: "handlebars",
|
|
3521
|
-
* subject: "Welcome, {{ first_name }}!",
|
|
3522
|
-
* html: "<h1>Hi {{ first_name }}</h1>",
|
|
3523
|
-
* });
|
|
3524
|
-
* console.log(tpl.id, tpl.revision); // "emt_…", 0
|
|
3525
|
-
*/
|
|
3526
|
-
create(params: EmailTemplateCreateParams, options?: RequestOptions): APIPromise<EmailTemplate>;
|
|
3527
|
-
/**
|
|
3528
|
-
* List the workspace's templates, newest first. `await` resolves the first
|
|
3529
|
-
* page; `for await` walks every template across all pages. Filter by
|
|
3530
|
-
* `category`, `source`, or a case-insensitive `name` prefix.
|
|
3531
|
-
*
|
|
3532
|
-
* @example Iterate every template, or take one page
|
|
3533
|
-
* for await (const tpl of bird.emailTemplates.list({ category: "transactional" })) {
|
|
3534
|
-
* console.log(tpl.id, tpl.name);
|
|
3535
|
-
* }
|
|
3536
|
-
* const page = await bird.emailTemplates.list({ limit: 50 }); // page.data, page.next_cursor
|
|
3537
|
-
*/
|
|
3538
|
-
list(query?: EmailTemplateListQuery, options?: RequestOptions): PaginatedPromise<EmailTemplateSummary>;
|
|
3539
|
-
/**
|
|
3540
|
-
* Fetch a template with its current draft content (subject, HTML, text), the
|
|
3541
|
-
* draft `revision`, and its draft/published version ids.
|
|
3542
|
-
*
|
|
3543
|
-
* @example
|
|
3544
|
-
* const tpl = await bird.emailTemplates.get("emt_abc123");
|
|
3545
|
-
* tpl.subject;
|
|
3546
|
-
* tpl.published_version_id; // null until first publish
|
|
3547
|
-
*/
|
|
3548
|
-
get(templateId: string, options?: RequestOptions): APIPromise<EmailTemplate>;
|
|
3549
|
-
/**
|
|
3550
|
-
* Update a template's metadata and draft content. Only the fields you send
|
|
3551
|
-
* change. Pass the draft `revision` you last read; if another edit landed
|
|
3552
|
-
* first the call throws a `BirdConflictError` — reload and retry.
|
|
3553
|
-
*
|
|
3554
|
-
* @example Edit the draft, guarded by the revision you read
|
|
3555
|
-
* const tpl = await bird.emailTemplates.get("emt_abc123");
|
|
3556
|
-
* const updated = await bird.emailTemplates.update("emt_abc123", {
|
|
3557
|
-
* revision: tpl.revision,
|
|
3558
|
-
* subject: "Welcome aboard, {{ first_name }}!",
|
|
3559
|
-
* });
|
|
3560
|
-
*/
|
|
3561
|
-
update(templateId: string, params: EmailTemplateUpdateParams, options?: RequestOptions): APIPromise<EmailTemplate>;
|
|
3562
|
-
/**
|
|
3563
|
-
* Delete a template and all its versions. The name becomes available for
|
|
3564
|
-
* reuse in the workspace.
|
|
3565
|
-
*
|
|
3566
|
-
* @example
|
|
3567
|
-
* await bird.emailTemplates.delete("emt_abc123");
|
|
3568
|
-
*/
|
|
3569
|
-
delete(templateId: string, options?: RequestOptions): APIPromise<void>;
|
|
3570
|
-
/**
|
|
3571
|
-
* Publish the current draft as a new immutable, numbered version and make it
|
|
3572
|
-
* the live version used by sends. The draft stays editable. The draft must
|
|
3573
|
-
* have a subject and a body, or the call throws.
|
|
3574
|
-
*
|
|
3575
|
-
* @example Publish, then send by template
|
|
3576
|
-
* const version = await bird.emailTemplates.publish("emt_abc123");
|
|
3577
|
-
* console.log(version.version_number); // 1, 2, 3…
|
|
3578
|
-
* await bird.email.send({
|
|
3579
|
-
* from: "hello@acme.com",
|
|
3580
|
-
* to: ["alice@example.com"],
|
|
3581
|
-
* template: { id: "emt_abc123", parameters: { first_name: "Alice" } },
|
|
3582
|
-
* });
|
|
3583
|
-
*/
|
|
3584
|
-
publish(templateId: string, options?: RequestOptions): APIPromise<EmailTemplateVersion>;
|
|
3585
|
-
/**
|
|
3586
|
-
* List every version of a template — the current draft plus all published
|
|
3587
|
-
* versions — newest first. Returns the full set in one response (`.data`);
|
|
3588
|
-
* this list is not paginated.
|
|
3589
|
-
*
|
|
3590
|
-
* @example
|
|
3591
|
-
* const { data } = await bird.emailTemplates.listVersions("emt_abc123");
|
|
3592
|
-
* for (const v of data) console.log(v.version_number, v.status);
|
|
3593
|
-
*/
|
|
3594
|
-
listVersions(templateId: string, options?: RequestOptions): APIPromise<EmailTemplateVersionList>;
|
|
3595
|
-
/**
|
|
3596
|
-
* Fetch a single version of a template.
|
|
3597
|
-
*
|
|
3598
|
-
* @example
|
|
3599
|
-
* const version = await bird.emailTemplates.getVersion("emt_abc123", "emv_def456");
|
|
3600
|
-
* version.status; // "draft" | "published"
|
|
3601
|
-
*/
|
|
3602
|
-
getVersion(templateId: string, versionId: string, options?: RequestOptions): APIPromise<EmailTemplateVersion>;
|
|
3603
|
-
}
|
|
3604
|
-
//#endregion
|
|
3605
3575
|
//#region src/resources/sms.d.ts
|
|
3606
3576
|
/** Body for `bird.sms.send` — supply either `text` (with `category`) or `template`. */
|
|
3607
3577
|
type SmsSendParams = SmsMessageSendRequest;
|
|
@@ -3691,6 +3661,79 @@ declare class SmsTemplatesResource extends Resource {
|
|
|
3691
3661
|
get(templateRef: string, options?: RequestOptions): APIPromise<SmsTemplate>;
|
|
3692
3662
|
}
|
|
3693
3663
|
//#endregion
|
|
3664
|
+
//#region src/resources/whatsapp.d.ts
|
|
3665
|
+
/** Body for `bird.whatsapp.send` — a template send; Bird picks the sender from the template's category. */
|
|
3666
|
+
type WhatsappSendParams = SendWhatsAppMessageRequest;
|
|
3667
|
+
/** Filters and cursor params for `bird.whatsapp.list`. */
|
|
3668
|
+
type WhatsappListQuery = NonNullable<ListWhatsAppMessagesData["query"]>;
|
|
3669
|
+
/** Filter for `bird.whatsapp.listEvents`. */
|
|
3670
|
+
type WhatsappListEventsQuery = NonNullable<ListWhatsAppMessageEventsData["query"]>;
|
|
3671
|
+
declare class WhatsappResource extends Resource {
|
|
3672
|
+
/**
|
|
3673
|
+
* Send a template message. Bird selects the sender number from the
|
|
3674
|
+
* template's category, so there is no sender field on the request. The
|
|
3675
|
+
* result is `accepted`, not yet delivered — read it back with `get` to
|
|
3676
|
+
* confirm.
|
|
3677
|
+
*
|
|
3678
|
+
* @example
|
|
3679
|
+
* const msg = await bird.whatsapp.send({
|
|
3680
|
+
* to: "+15551234567",
|
|
3681
|
+
* template: {
|
|
3682
|
+
* name: "bird_otp",
|
|
3683
|
+
* components: [
|
|
3684
|
+
* { type: "body", parameters: [{ type: "text", text: "123456" }] },
|
|
3685
|
+
* ],
|
|
3686
|
+
* },
|
|
3687
|
+
* });
|
|
3688
|
+
* console.log(msg.id, msg.status);
|
|
3689
|
+
*/
|
|
3690
|
+
send(params: WhatsappSendParams, options?: RequestOptions): APIPromise<WhatsAppMessage>;
|
|
3691
|
+
/**
|
|
3692
|
+
* Fetch a single WhatsApp message: its current delivery status and failure
|
|
3693
|
+
* detail if it failed.
|
|
3694
|
+
*
|
|
3695
|
+
* @example
|
|
3696
|
+
* const msg = await bird.whatsapp.get("wa_abc123");
|
|
3697
|
+
* msg.status; // "accepted" | "delivered" | …
|
|
3698
|
+
*/
|
|
3699
|
+
get(messageId: string, options?: RequestOptions): APIPromise<WhatsAppMessage>;
|
|
3700
|
+
/**
|
|
3701
|
+
* List WhatsApp messages, newest first. `await` resolves the first page;
|
|
3702
|
+
* `for await` walks every message across all pages. Filter by status,
|
|
3703
|
+
* recipient phone number, or business-scoped user ID.
|
|
3704
|
+
*
|
|
3705
|
+
* @example
|
|
3706
|
+
* for await (const msg of bird.whatsapp.list({ status: ["delivered"] })) {
|
|
3707
|
+
* console.log(msg.id, msg.status);
|
|
3708
|
+
* }
|
|
3709
|
+
*/
|
|
3710
|
+
list(query?: WhatsappListQuery, options?: RequestOptions): PaginatedPromise<WhatsAppMessage>;
|
|
3711
|
+
/**
|
|
3712
|
+
* List a WhatsApp message's lifecycle event timeline, in chronological
|
|
3713
|
+
* order. The timeline is bounded and returned in full — this list is not
|
|
3714
|
+
* paginated.
|
|
3715
|
+
*
|
|
3716
|
+
* @example
|
|
3717
|
+
* const { data } = await bird.whatsapp.listEvents("wa_abc123");
|
|
3718
|
+
* for (const event of data) console.log(event.type, event.occurred_at);
|
|
3719
|
+
*/
|
|
3720
|
+
listEvents(messageId: string, query?: WhatsappListEventsQuery, options?: RequestOptions): APIPromise<WhatsAppEventList>;
|
|
3721
|
+
}
|
|
3722
|
+
//#endregion
|
|
3723
|
+
//#region src/resources/whatsappTemplates.d.ts
|
|
3724
|
+
declare class WhatsappTemplatesResource extends Resource {
|
|
3725
|
+
/**
|
|
3726
|
+
* List the WhatsApp message templates available to the workspace — Meta's
|
|
3727
|
+
* approved templates for this business account. The catalogue is small and
|
|
3728
|
+
* returned in full (`.data`); this list is not paginated.
|
|
3729
|
+
*
|
|
3730
|
+
* @example
|
|
3731
|
+
* const { data } = await bird.whatsappTemplates.list();
|
|
3732
|
+
* for (const tpl of data) console.log(tpl.name, tpl.status);
|
|
3733
|
+
*/
|
|
3734
|
+
list(options?: RequestOptions): APIPromise<WhatsAppTemplateList>;
|
|
3735
|
+
}
|
|
3736
|
+
//#endregion
|
|
3694
3737
|
//#region src/resources/webhooks.d.ts
|
|
3695
3738
|
/** A verified webhook event — discriminated on `type` (ADR-0028 wire contract). */
|
|
3696
3739
|
type BirdWebhookEvent = WebhookEvent;
|
|
@@ -3820,12 +3863,14 @@ declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions>
|
|
|
3820
3863
|
protected readonly core: BirdHTTPClient;
|
|
3821
3864
|
/** The email channel — `bird.email.send(...)`, `.get(...)`, `.list(...)`. */
|
|
3822
3865
|
readonly email: EmailResource<EmailDefaultsOf<O>>;
|
|
3823
|
-
/** Email templates — `bird.emailTemplates.create(...)`, `.list(...)`, `.publish(...)`, … */
|
|
3824
|
-
readonly emailTemplates: EmailTemplatesResource;
|
|
3825
3866
|
/** The SMS channel — `bird.sms.send(...)`, `.get(...)`, `.list(...)`. */
|
|
3826
3867
|
readonly sms: SmsResource;
|
|
3827
3868
|
/** SMS templates — `bird.smsTemplates.list(...)`, `.get(...)`. */
|
|
3828
3869
|
readonly smsTemplates: SmsTemplatesResource;
|
|
3870
|
+
/** The WhatsApp channel — `bird.whatsapp.send(...)`, `.get(...)`, `.list(...)`, `.listEvents(...)`. */
|
|
3871
|
+
readonly whatsapp: WhatsappResource;
|
|
3872
|
+
/** WhatsApp templates — `bird.whatsappTemplates.list(...)`. */
|
|
3873
|
+
readonly whatsappTemplates: WhatsappTemplatesResource;
|
|
3829
3874
|
/** Contacts — `bird.contacts.create(...)`, `.list(...)`, `.get(...)`, `.batch(...)`, … */
|
|
3830
3875
|
readonly contacts: ContactsResource;
|
|
3831
3876
|
/** Audiences — `bird.audiences.create(...)`, `.list(...)`, `.addContacts(...)`, … */
|
|
@@ -3876,8 +3921,6 @@ declare const WebhookEventType: {
|
|
|
3876
3921
|
readonly EmailMailboxMessageDelivered: "email_mailbox.message_delivered";
|
|
3877
3922
|
readonly EmailMailboxMessageFailed: "email_mailbox.message_failed";
|
|
3878
3923
|
readonly EmailMailboxMessageReceived: "email_mailbox.message_received";
|
|
3879
|
-
readonly EmailMailboxMessageReceivedBlocked: "email_mailbox.message_received_blocked";
|
|
3880
|
-
readonly EmailMailboxMessageReceivedUnauthenticated: "email_mailbox.message_received_unauthenticated";
|
|
3881
3924
|
readonly EmailMailboxMessageSent: "email_mailbox.message_sent";
|
|
3882
3925
|
readonly EmailMailboxSuspended: "email_mailbox.suspended";
|
|
3883
3926
|
readonly EmailMailboxThreadCreated: "email_mailbox.thread_created";
|
|
@@ -3900,5 +3943,5 @@ declare const WebhookEventType: {
|
|
|
3900
3943
|
/** A known webhook event type value. */
|
|
3901
3944
|
type WebhookEventTypeValue = (typeof WebhookEventType)[keyof typeof WebhookEventType];
|
|
3902
3945
|
//#endregion
|
|
3903
|
-
export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceContactsQuery, type AudienceCreateParams, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type
|
|
3946
|
+
export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceContactsQuery, type AudienceCreateParams, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type ErrorDetail, type ErrorNextAction, type PaginatedPromise, type RequestOptions, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, type UnmetGate, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, type WhatsAppEventList, type WhatsAppMessage, type WhatsAppTemplate, type WhatsAppTemplateList, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, baseUrlForRegion, regionFromApiKey };
|
|
3904
3947
|
//# sourceMappingURL=index.d.mts.map
|