API reference · Subscribers
Add a subscriber
POST
/api/v1/subscribersAdds a person who agreed to hear from you. If the number is already a subscriber, its tags and fields are merged and you get 200. Someone who opted out is never re-subscribed: you get 409 subscriber_opted_out, and only they can opt back in.
- Authentication
- Bearer token in the
Authorizationheader. - Required scopes
subscribers:write- Idempotency
Idempotency-Keyis optional. Retry guidance
Parameters
Request headers
Idempotency-KeystringOptionalA unique key for this request (up to 255 characters). A retry with the same key returns the first response.
Maximum length:
255
Request body
application/json · Required
Only the listed fields are accepted.
phonestringRequiredPhone number in E.164 format. Spaces and dashes are allowed.
Maximum length:
32namestringOptionalMaximum length:
120tagsarrayOptionalMaximum items:
50View tags structure
Array items: string
Minimum length:
1Maximum length:
40external_idstringOptionalYour own ID for this person, unique per workspace and mode.
Minimum length:
1Maximum length:
200attributesobjectOptionalYour own fields for this subscriber: strings, numbers, booleans. Null removes a field.
View attributes structure
Additional field values: multiple types
Must match at least one of these structures.
Option 1: string
Maximum length:
500Option 2: number
Option 3: boolean
Option 4: null
Field name requirements
Minimum length:
1Maximum length:
40Pattern:
^[A-Za-z0-9_.-]+$consentobjectOptionalEvidence of consent, stored with the subscriber's consent history.
Only the listed fields are accepted.
View consent structure
Only the listed fields are accepted.
sourcestringOptionalWhere you collected consent, e.g. checkout_form.
Minimum length:
1Maximum length:
60textstringOptionalThe consent wording the person agreed to.
Maximum length:
2000collected_atstringOptionalRFC 3339 time.
Format:
date-timePattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ipmultiple typesOptionalThe person's IP address when they agreed.
View ip structure
Must match at least one of these structures.
Option 1: string
Format:
ipv4Pattern:
^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$Option 2: string
Format:
ipv6Pattern:
^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$
Request example
Run on your server or in a terminal. Replace YOUR_ placeholders and set BUDDY_API_KEY. Reuse the idempotency key only when retrying the same request.
Run in bash or zsh with curl 7.76+. Set BUDDY_API_KEY first and replace YOUR_ placeholders before running.
curl --fail-with-body --request POST 'https://usebuddy.app/api/v1/subscribers' \
--header "Authorization: Bearer $BUDDY_API_KEY" \
--header "Idempotency-Key: YOUR_UNIQUE_OPERATION_ID" \
--header "Content-Type: application/json" \
--data '{
"phone": "+44 7700 900123",
"name": "Amira",
"tags": [
"early-list"
],
"external_id": "cus_1042",
"consent": {
"source": "checkout_form",
"text": "Send me order updates on WhatsApp",
"collected_at": "2026-10-15T09:30:00Z"
}
}'Responses
200The number was already a subscriber; tags and fields were merged.
application/json
dataobjectRequiredView data structure
idstringRequiredID starting with sub_.
Pattern:
^sub_[0-9a-f]{32}$phonestringRequiredPhone number in E.164 format.
namestring | nullRequiredstatusstringRequiredopted_out once the person replied STOP or opted out any other way.
Allowed values:
"subscribed","opted_out"tagsarrayRequiredView tags structure
Array items: string
external_idstring | nullRequiredattributesobjectRequiredView attributes structure
Additional field values: string | number | boolean
Field name requirements
sourcestring | nullRequiredWhere the subscriber came from.
livemodebooleanRequiredcreated_atstringRequiredRFC 3339 time.
Format:
date-timePattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atmultiple typesRequiredView updated_at structure
Must match at least one of these structures.
Option 1: string
RFC 3339 time.
Format:
date-timePattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Option 2: null
Response headers
Buddy-Request-Id- This request's ID (req_...). Quote it to support.
Buddy-Api-Version- The dated build of v1 that served the request.
RateLimit-Limit- Requests allowed in the current window.
RateLimit-Remaining- Requests left in the current window.
RateLimit-Reset- Seconds until the window resets.
Idempotent-Replayed- true when this is the stored response of an earlier request with the same Idempotency-Key.
201The subscriber was created.
application/json
dataobjectRequiredView data structure
idstringRequiredID starting with sub_.
Pattern:
^sub_[0-9a-f]{32}$phonestringRequiredPhone number in E.164 format.
namestring | nullRequiredstatusstringRequiredopted_out once the person replied STOP or opted out any other way.
Allowed values:
"subscribed","opted_out"tagsarrayRequiredView tags structure
Array items: string
external_idstring | nullRequiredattributesobjectRequiredView attributes structure
Additional field values: string | number | boolean
Field name requirements
sourcestring | nullRequiredWhere the subscriber came from.
livemodebooleanRequiredcreated_atstringRequiredRFC 3339 time.
Format:
date-timePattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atmultiple typesRequiredView updated_at structure
Must match at least one of these structures.
Option 1: string
RFC 3339 time.
Format:
date-timePattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Option 2: null
Response headers
Buddy-Request-Id- This request's ID (req_...). Quote it to support.
Buddy-Api-Version- The dated build of v1 that served the request.
RateLimit-Limit- Requests allowed in the current window.
RateLimit-Remaining- Requests left in the current window.
RateLimit-Reset- Seconds until the window resets.
Idempotent-Replayed- true when this is the stored response of an earlier request with the same Idempotency-Key.
Errors
Use the error code to decide how to recover. See the error reference for guidance.
| HTTP status | Error codes |
|---|---|
400 | invalid_phone: Invalid phone number. invalid_request: Invalid request. unknown_field: Unknown field. invalid_json: Invalid JSON. invalid_idempotency_key: Invalid idempotency key |
401 | unauthorized: Unauthorized. api_key_expired: API key expired. api_key_revoked: API key revoked. token_expired: Access token expired |
403 | api_not_enabled: API access not enabled. merchant_agreement_required: Merchant agreement required. insufficient_scope: Insufficient scope |
409 | subscriber_opted_out: Subscriber opted out. external_id_taken: External ID in use. resource_erased: Resource erased. idempotency_key_reused: Idempotency key reused. request_in_progress: Request in progress |
413 | payload_too_large: Payload too large |
415 | unsupported_media_type: Unsupported media type |
429 | rate_limited: Rate limited |
500 | internal_error: Internal error |
503 | service_unavailable: Service unavailable |
Error response structure
errorstringRequiredStable error code.
messagestringRequiredWhat went wrong and how to fix it.
paramstringOptionalThe field the error is about.
request_idstringRequiredQuote this when contacting support.
doc_urlstringRequiredDocumentation for this error code.
detailsobjectOptionalView details structure
Additional field values: any value
Field name requirements
Complete OpenAPI schema
This operation and its schema definitions are also available in the OpenAPI document.
{
"operation": {
"operationId": "createSubscriber",
"summary": "Add a subscriber",
"description": "Adds a person who agreed to hear from you. If the number is already a subscriber, its tags and fields are merged and you get 200. Someone who opted out is never re-subscribed: you get 409 subscriber_opted_out, and only they can opt back in.",
"tags": [
"Subscribers"
],
"x-buddy-scopes": [
"subscribers:write"
],
"x-buddy-errors": [
"invalid_phone",
"subscriber_opted_out",
"external_id_taken",
"unauthorized",
"api_key_expired",
"api_key_revoked",
"token_expired",
"api_not_enabled",
"merchant_agreement_required",
"insufficient_scope",
"invalid_request",
"unknown_field",
"invalid_json",
"payload_too_large",
"unsupported_media_type",
"resource_erased",
"invalid_idempotency_key",
"idempotency_key_reused",
"request_in_progress",
"rate_limited",
"service_unavailable",
"internal_error"
],
"security": [
{
"bearerAuth": []
},
{
"oauth2": [
"subscribers:write"
]
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "A unique key for this request (up to 255 characters). A retry with the same key returns the first response.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "The number was already a subscriber; tags and fields were merged.",
"headers": {
"Buddy-Request-Id": {
"$ref": "#/components/headers/BuddyRequestId"
},
"Buddy-Api-Version": {
"$ref": "#/components/headers/BuddyApiVersion"
},
"RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"Idempotent-Replayed": {
"$ref": "#/components/headers/IdempotentReplayed"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Subscriber"
}
}
}
}
}
},
"201": {
"description": "The subscriber was created.",
"headers": {
"Buddy-Request-Id": {
"$ref": "#/components/headers/BuddyRequestId"
},
"Buddy-Api-Version": {
"$ref": "#/components/headers/BuddyApiVersion"
},
"RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"Idempotent-Replayed": {
"$ref": "#/components/headers/IdempotentReplayed"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Subscriber"
}
}
}
}
}
},
"400": {
"description": "`invalid_phone`: Invalid phone number. `invalid_request`: Invalid request. `unknown_field`: Unknown field. `invalid_json`: Invalid JSON. `invalid_idempotency_key`: Invalid idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`unauthorized`: Unauthorized. `api_key_expired`: API key expired. `api_key_revoked`: API key revoked. `token_expired`: Access token expired",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`api_not_enabled`: API access not enabled. `merchant_agreement_required`: Merchant agreement required. `insufficient_scope`: Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "`subscriber_opted_out`: Subscriber opted out. `external_id_taken`: External ID in use. `resource_erased`: Resource erased. `idempotency_key_reused`: Idempotency key reused. `request_in_progress`: Request in progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "`payload_too_large`: Payload too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "`unsupported_media_type`: Unsupported media type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`rate_limited`: Rate limited",
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "`internal_error`: Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "`service_unavailable`: Service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"description": "Phone number in E.164 format. Spaces and dashes are allowed.",
"type": "string",
"maxLength": 32
},
"name": {
"type": "string",
"maxLength": 120
},
"tags": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
},
"external_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Your own ID for this person, unique per workspace and mode."
},
"attributes": {
"type": "object",
"propertyNames": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^[A-Za-z0-9_.-]+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"description": "Your own fields for this subscriber: strings, numbers, booleans. Null removes a field."
},
"consent": {
"type": "object",
"properties": {
"source": {
"description": "Where you collected consent, e.g. checkout_form.",
"type": "string",
"minLength": 1,
"maxLength": 60
},
"text": {
"description": "The consent wording the person agreed to.",
"type": "string",
"maxLength": 2000
},
"collected_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"ip": {
"description": "The person's IP address when they agreed.",
"anyOf": [
{
"type": "string",
"format": "ipv4",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
},
{
"type": "string",
"format": "ipv6",
"pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$"
}
]
}
},
"additionalProperties": false,
"description": "Evidence of consent, stored with the subscriber's consent history."
}
},
"required": [
"phone"
],
"additionalProperties": false
},
"example": {
"phone": "+44 7700 900123",
"name": "Amira",
"tags": [
"early-list"
],
"external_id": "cus_1042",
"consent": {
"source": "checkout_form",
"text": "Send me order updates on WhatsApp",
"collected_at": "2026-10-15T09:30:00Z"
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "A live key (bd_live_...) or a test key (bd_test_...). Test keys only see test data. An OAuth access token (bdo_...) works here too."
},
"oauth2": {
"type": "oauth2",
"description": "For apps that act for other Buddy workspaces: the authorization code flow with PKCE (S256). Access tokens (bdo_...) last an hour; refresh tokens rotate on every use. Requests may also use the group names subscribers, messages, templates, campaigns, events, webhooks and results.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://usebuddy.app/oauth/authorize",
"tokenUrl": "https://usebuddy.app/oauth/token",
"refreshUrl": "https://usebuddy.app/oauth/token",
"scopes": {
"subscribers:read": "Read subscribers, tags and consent history",
"subscribers:write": "Create, update, tag, opt out and erase subscribers",
"messages:read": "Read message status",
"messages:send": "Send messages",
"templates:read": "List message templates",
"campaigns:read": "Read campaigns and their results",
"campaigns:write": "Create draft campaigns",
"campaigns:send": "Send, schedule and cancel campaigns",
"events:write": "Send events",
"webhooks:read": "Read webhook endpoints and deliveries",
"webhooks:write": "Manage webhook endpoints"
}
}
}
}
},
"headers": {
"BuddyRequestId": {
"description": "This request's ID (req_...). Quote it to support.",
"schema": {
"type": "string"
}
},
"BuddyApiVersion": {
"description": "The dated build of v1 that served the request.",
"schema": {
"type": "string"
}
},
"RateLimitLimit": {
"description": "Requests allowed in the current window.",
"schema": {
"type": "integer"
}
},
"RateLimitRemaining": {
"description": "Requests left in the current window.",
"schema": {
"type": "integer"
}
},
"RateLimitReset": {
"description": "Seconds until the window resets.",
"schema": {
"type": "integer"
}
},
"RetryAfter": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
},
"IdempotentReplayed": {
"description": "true when this is the stored response of an earlier request with the same Idempotency-Key.",
"schema": {
"type": "string"
}
}
},
"schemas": {
"ConsentEvent": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ce_[0-9a-f]{32}$",
"description": "ID starting with ce_."
},
"type": {
"type": "string",
"description": "opt_in or opt_out."
},
"source": {
"type": [
"string",
"null"
]
},
"ip": {
"type": [
"string",
"null"
]
},
"evidence": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
}
},
"required": [
"id",
"type",
"source",
"ip",
"evidence",
"created_at"
]
},
"DeletedSubscriber": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^sub_[0-9a-f]{32}$",
"description": "ID starting with sub_."
},
"deleted": {
"type": "boolean",
"const": true
}
},
"required": [
"id",
"deleted"
]
},
"DeletedWebhookEndpoint": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"description": "ID starting with we_."
},
"deleted": {
"type": "boolean",
"const": true
}
},
"required": [
"id",
"deleted"
]
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Stable error code."
},
"message": {
"type": "string",
"description": "What went wrong and how to fix it."
},
"param": {
"description": "The field the error is about.",
"type": "string"
},
"request_id": {
"type": "string",
"description": "Quote this when contacting support."
},
"doc_url": {
"type": "string",
"description": "Documentation for this error code."
},
"details": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"error",
"message",
"request_id",
"doc_url"
]
},
"Me": {
"type": "object",
"properties": {
"workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ws_[0-9a-f]{32}$",
"description": "ID starting with ws_."
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"credential": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"api_key",
"oauth_token"
]
},
"id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"prefix": {
"type": [
"string",
"null"
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"name",
"prefix",
"expires_at"
]
},
"livemode": {
"type": "boolean"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"plan": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"api_included": {
"type": "boolean",
"description": "Whether live API keys work on this plan. Test keys work on every plan."
}
},
"required": [
"id",
"name",
"api_included"
]
},
"rate_limits": {
"type": "object",
"properties": {
"key": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"window_seconds": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"limit",
"window_seconds"
]
},
"workspace": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"window_seconds": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"limit",
"window_seconds"
]
}
},
"required": [
"key",
"workspace"
]
},
"whatsapp": {
"type": "object",
"properties": {
"connected": {
"type": "boolean"
},
"phone_number": {
"description": "The connected number, as WhatsApp displays it.",
"type": [
"string",
"null"
]
}
},
"required": [
"connected",
"phone_number"
]
},
"usage": {
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "YYYY-MM, in UTC."
},
"sends": {
"type": "object",
"properties": {
"used": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"used",
"limit"
]
},
"api_calls": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"period",
"sends",
"api_calls"
]
}
},
"required": [
"workspace",
"credential",
"livemode",
"scopes",
"plan",
"rate_limits",
"whatsapp",
"usage"
]
},
"Message": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^msg_[0-9a-f]{32}$",
"description": "ID starting with msg_."
},
"status": {
"type": "string",
"enum": [
"queued",
"sent",
"delivered",
"read",
"failed"
],
"description": "queued, sent, delivered, read or failed. Statuses only move forward."
},
"to": {
"type": "string",
"description": "Phone number in E.164 format."
},
"subscriber": {
"anyOf": [
{
"type": "string",
"pattern": "^sub_[0-9a-f]{32}$",
"description": "ID starting with sub_."
},
{
"type": "null"
}
],
"description": "The subscriber with this number, if there is one."
},
"type": {
"type": "string",
"enum": [
"template",
"text"
]
},
"template": {
"description": "The template name.",
"type": [
"string",
"null"
]
},
"language": {
"type": [
"string",
"null"
]
},
"category": {
"description": "marketing, utility or authentication.",
"type": [
"string",
"null"
]
},
"transactional": {
"type": "boolean"
},
"status_at": {
"type": "object",
"properties": {
"queued": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"sent": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"delivered": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"read": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"failed": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
}
},
"description": "When each status was first seen."
},
"error": {
"description": "A stable code when the message failed, such as recipient_unavailable.",
"type": [
"string",
"null"
]
},
"reason": {
"description": "Why it failed, in plain English.",
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"status",
"to",
"subscriber",
"type",
"template",
"language",
"category",
"transactional",
"status_at",
"error",
"reason",
"metadata",
"livemode",
"created_at",
"updated_at"
]
},
"Subscriber": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^sub_[0-9a-f]{32}$",
"description": "ID starting with sub_."
},
"phone": {
"type": "string",
"description": "Phone number in E.164 format."
},
"name": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"subscribed",
"opted_out"
],
"description": "opted_out once the person replied STOP or opted out any other way."
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"external_id": {
"type": [
"string",
"null"
]
},
"attributes": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"source": {
"description": "Where the subscriber came from.",
"type": [
"string",
"null"
]
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"phone",
"name",
"status",
"tags",
"external_id",
"attributes",
"source",
"livemode",
"created_at",
"updated_at"
]
},
"TagCount": {
"type": "object",
"properties": {
"tag": {
"type": "string"
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"tag",
"count"
]
},
"Template": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^tpl_[0-9a-f]{32}$",
"description": "ID starting with tpl_."
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"category": {
"description": "marketing, utility or authentication.",
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"description": "approved, pending, rejected, paused, disabled, ..."
},
"quality_rating": {
"type": [
"string",
"null"
]
},
"body": {
"type": "string"
},
"header_text": {
"type": [
"string",
"null"
]
},
"footer": {
"type": [
"string",
"null"
]
},
"parameters": {
"$ref": "#/components/schemas/TemplateParameters"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"language",
"category",
"status",
"quality_rating",
"body",
"header_text",
"footer",
"parameters",
"created_at",
"updated_at"
]
},
"TemplateButton": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Position of the button, from 0."
},
"type": {
"type": "string",
"description": "url, quick_reply, phone_number, copy_code, otp, flow, ..."
},
"text": {
"type": [
"string",
"null"
]
},
"url": {
"description": "The URL pattern for url buttons.",
"type": [
"string",
"null"
]
},
"takes_parameter": {
"type": "boolean",
"description": "True when a send must provide a value for this button."
},
"parameter": {
"anyOf": [
{
"type": "string",
"enum": [
"url_suffix",
"coupon_code",
"otp_code"
]
},
{
"type": "null"
}
],
"description": "What to send for this button: url_suffix (dynamic URL), coupon_code (copy code) or otp_code."
}
},
"required": [
"index",
"type",
"text",
"url",
"takes_parameter",
"parameter"
]
},
"TemplateParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "\"1\", \"2\", ... for positional templates, or the parameter name for named ones."
},
"example": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"example"
]
},
"TemplateParameters": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"positional",
"named",
"none"
]
},
"body": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TemplateParameter"
}
},
"header": {
"type": "object",
"properties": {
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"text",
"image",
"video",
"document",
"location"
]
},
{
"type": "null"
}
]
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TemplateParameter"
},
"description": "Text header parameters."
},
"media_required": {
"type": "boolean",
"description": "True when a send must provide header media or a location."
}
},
"required": [
"type",
"parameters",
"media_required"
]
},
"buttons": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TemplateButton"
}
}
},
"required": [
"format",
"body",
"header",
"buttons"
]
},
"WebhookDelivery": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^dlv_[0-9a-f]{32}$",
"description": "ID starting with dlv_."
},
"event_id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"event_type": {
"type": "string"
},
"webhook_endpoint": {
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"description": "ID starting with we_."
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
],
"description": "pending while attempts remain, then succeeded or failed."
},
"attempt": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Attempts made so far."
},
"response_status": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "The HTTP status of the last attempt."
},
"response_ms": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"response_snippet": {
"description": "The start of your endpoint's reply to the last attempt.",
"type": [
"string",
"null"
]
},
"error": {
"description": "Why the last attempt failed, when it did.",
"type": [
"string",
"null"
]
},
"next_attempt_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
]
},
"resent_from": {
"anyOf": [
{
"type": "string",
"pattern": "^dlv_[0-9a-f]{32}$",
"description": "ID starting with dlv_."
},
{
"type": "null"
}
]
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
}
},
"required": [
"id",
"event_id",
"event_type",
"webhook_endpoint",
"status",
"attempt",
"response_status",
"response_ms",
"response_snippet",
"error",
"next_attempt_at",
"resent_from",
"livemode",
"created_at",
"updated_at"
]
},
"WebhookEndpoint": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"description": "ID starting with we_."
},
"url": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"disabled_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"manual",
"gone",
"failing"
],
"description": "Why the endpoint is off: you turned it off, it answered 410 Gone, or every delivery failed for 3 days."
},
{
"type": "null"
}
]
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
}
},
"required": [
"id",
"url",
"description",
"events",
"status",
"disabled_reason",
"livemode",
"created_at",
"updated_at"
]
},
"WebhookEndpointSecret": {
"type": "object",
"properties": {
"secret": {
"type": "string",
"description": "The current signing secret (whsec_...)."
},
"previous_secret_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
{
"type": "null"
}
],
"description": "While set, deliveries are also signed with the previous secret until this time."
}
},
"required": [
"secret",
"previous_secret_expires_at"
]
},
"WebhookEndpointWithSecret": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"description": "ID starting with we_."
},
"url": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"disabled_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"manual",
"gone",
"failing"
],
"description": "Why the endpoint is off: you turned it off, it answered 410 Gone, or every delivery failed for 3 days."
},
{
"type": "null"
}
]
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"updated_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"secret": {
"type": "string",
"description": "The signing secret (whsec_...). Verify the Buddy-Signature header of every delivery with it."
}
},
"required": [
"id",
"url",
"description",
"events",
"status",
"disabled_reason",
"livemode",
"created_at",
"updated_at",
"secret"
]
},
"WebhookEvent": {
"oneOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"message.sent",
"message.delivered",
"message.read",
"message.failed"
]
},
"data": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"pattern": "^msg_[0-9a-f]{32}$",
"description": "ID starting with msg_."
},
"to": {
"type": "string"
},
"subscriber": {
"anyOf": [
{
"type": "string",
"pattern": "^sub_[0-9a-f]{32}$",
"description": "ID starting with sub_."
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"sent",
"delivered",
"read",
"failed"
]
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"template": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"error": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
}
},
"required": [
"message_id",
"to",
"subscriber",
"status",
"at",
"template",
"metadata"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"const": "message.replied"
},
"data": {
"type": "object",
"properties": {
"message_id": {
"anyOf": [
{
"type": "string",
"pattern": "^msg_[0-9a-f]{32}$",
"description": "ID starting with msg_."
},
{
"type": "null"
}
]
},
"subscriber": {
"anyOf": [
{
"type": "string",
"pattern": "^sub_[0-9a-f]{32}$",
"description": "ID starting with sub_."
},
{
"type": "null"
}
]
},
"text": {
"type": "string"
}
},
"required": [
"message_id",
"subscriber",
"text"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"subscriber.created",
"subscriber.updated",
"subscriber.tagged",
"subscriber.opted_in"
]
},
"data": {
"type": "object",
"properties": {
"subscriber": {
"$ref": "#/components/schemas/Subscriber"
},
"source": {
"type": "string"
},
"added": {
"type": "array",
"items": {
"type": "string"
}
},
"removed": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"subscriber"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"const": "subscriber.opted_out"
},
"data": {
"type": "object",
"properties": {
"subscriber": {
"anyOf": [
{
"$ref": "#/components/schemas/Subscriber"
},
{
"type": "null"
}
]
},
"phone": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"subscriber",
"reason"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"campaign.sent",
"campaign.completed"
]
},
"data": {
"type": "object",
"properties": {
"campaign_id": {
"type": "string",
"pattern": "^cmp_[0-9a-f]{32}$",
"description": "ID starting with cmp_."
},
"status": {
"type": "string"
}
},
"required": [
"campaign_id",
"status"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"const": "template.status_updated"
},
"data": {
"type": "object",
"properties": {
"template": {
"$ref": "#/components/schemas/Template"
},
"event": {
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
}
},
"required": [
"template",
"event",
"reason"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"description": "ID starting with evt_."
},
"version": {
"type": "string",
"const": "1"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "RFC 3339 time."
},
"livemode": {
"type": "boolean"
},
"type": {
"type": "string",
"const": "ping"
},
"data": {
"type": "object",
"properties": {
"webhook_endpoint": {
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"description": "ID starting with we_."
}
},
"required": [
"webhook_endpoint"
]
}
},
"required": [
"id",
"version",
"at",
"livemode",
"type",
"data"
]
}
]
}
}
}
}