API reference
Connect a WhatsApp Business Account from Meta and assign its numbers to assistants.
- GET
/api/integrations/whatsapp/connectionsList WhatsApp accounts and numbers - POST
/api/integrations/whatsapp/connectionsConnect a WhatsApp Business account - PATCH
/api/integrations/whatsapp/connections/{id}Update a WhatsApp connection - DELETE
/api/integrations/whatsapp/connections/{id}Disconnect a WhatsApp account - POST
/api/integrations/whatsapp/connections/{id}/embedded/retryRetry the remaining Embedded Signup steps - PUT
/api/integrations/whatsapp/connections/{id}/numbers/{numberId}Assign a WhatsApp number to an assistant - GET
/api/integrations/whatsapp/connections/{id}/operator-alertsRead an account's operator alert settings - PUT
/api/integrations/whatsapp/connections/{id}/operator-alertsSave an account's operator alert settings - POST
/api/integrations/whatsapp/connections/{id}/operator-alerts/testSend a test operator alert - POST
/api/integrations/whatsapp/connections/{id}/subscribeSubscribe an account to its message callback - POST
/api/integrations/whatsapp/connections/{id}/syncSync an account's phone numbers - GET
/api/integrations/whatsapp/connections/{id}/templatesList an account's message templates - POST
/api/integrations/whatsapp/connections/{id}/templatesCreate a message template - DELETE
/api/integrations/whatsapp/connections/{id}/templates/{name}Delete a message template - POST
/api/integrations/whatsapp/connections/{id}/templates/syncSync an account's message templates - POST
/api/integrations/whatsapp/connections/embeddedConnect an account through Embedded Signup - PUT
/api/integrations/whatsapp/contacts/{contactId}/marketing-opt-inRecord or withdraw marketing consent - GET
/api/integrations/whatsapp/conversations/{conversationId}/contactGet a conversation's WhatsApp contact - GET
/api/integrations/whatsapp/conversations/{conversationId}/deliveriesDelivery state of a conversation's messages - POST
/api/integrations/whatsapp/conversations/{conversationId}/templateSend a template message - GET
/api/integrations/whatsapp/conversations/{conversationId}/templatesList the templates a conversation can be sent - GET
/api/integrations/whatsapp/embedded-signupEmbedded Signup settings - GET
/api/integrations/whatsapp/numbers/{numberId}/linksList a number's campaign links - POST
/api/integrations/whatsapp/numbers/{numberId}/linksCreate a campaign link - PATCH
/api/integrations/whatsapp/numbers/{numberId}/links/{linkId}Update a campaign link - DELETE
/api/integrations/whatsapp/numbers/{numberId}/links/{linkId}Archive a campaign link - GET
/api/integrations/whatsapp/numbers/templatesList project WhatsApp numbers and approved templates
List WhatsApp accounts and numbers
GET/api/integrations/whatsapp/connections
Every connected WhatsApp Business Account with its numbers, the assistant each number is assigned to, and counts of replies and turns that failed. Credentials are never returned. Needs an org-wide key.
Secret API key, org-wide (not pinned to a project). How it works
Returns
200 Connections
Response attributes
dataarray of WhatsAppConnectionrequired17 attributes
idstringorg_idstringnamestringwaba_idstringThe WhatsApp Business Account id.
api_versionstringconfiguredbooleanCredentials are stored. False after a disconnect.
enabledbooleanFalse while paused: messages are not answered.
webhook_pathstringThe path of the callback URL to give Meta (on the API origin).
connected_viastringOne of
manualembeddedembedded_signupobject | nullEmbedded Signup only: the steps still to run after the connection was created, and why the last try stopped.
7 attributes
callback_originstringphone_number_idstring | nullcoexistencebooleanTrue when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.
pendingarray of stringNot run yet, or failed and to be retried. A step in neither
pendingnorskippedis done.skippedarray of stringRegistration is skipped when no
phone_number_idwas given or coexistence is true.failed_stepstring | nullOne of
subscriberegistersyncerrorstring | nullMeta's error code (
meta_<code>), never its message.
account_statusobject | nullThe latest
account_updateevent from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).3 attributes
eventstringdetailobjectatstringISO 8601 timestamp
review_statusstring | nullThe latest account review decision: APPROVED, REJECTED, PENDING.
health_updated_atstring | nullISO 8601 timestamptemplates_synced_atstring | nullISO 8601 timestampThe last template sync attempt.
templates_synced_ok_atstring | nullISO 8601 timestampThe last successful template sync.
templates_sync_errorstring | nullWhy the last template sync failed; null after a success.
numbersarray of WhatsAppNumber17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"waba_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"api_version": "string",
"configured": true,
"enabled": true,
"webhook_path": "string",
"connected_via": "manual",
"embedded_signup": {
"callback_origin": "https://www.example.com",
"phone_number_id": "+14155550123",
"coexistence": true,
"pending": [
"subscribe"
],
"skipped": [
"register"
],
"failed_step": "subscribe",
"error": "string"
},
"account_status": {
"event": "string",
"detail": {
"key": "string"
},
"at": "2026-10-28T09:30:00.000Z"
},
"review_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"templates_synced_at": "2026-10-28T09:30:00.000Z",
"templates_synced_ok_at": "2026-10-28T09:30:00.000Z",
"templates_sync_error": "string",
"numbers": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}
]
}Connect a WhatsApp Business account
POST/api/integrations/whatsapp/connections
Checks the credentials with Meta, stores them encrypted and imports the account's phone numbers, unassigned. Then subscribe the account to its callback and assign numbers to assistants. Needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Request body
namestringrequiredup to 100 charactersYour label for the account.
waba_idstringrequiredThe WhatsApp Business Account id (digits).
api_versionstringGraph API version.
Default
"v25.0"credentialsobjectrequiredFrom your Meta app. Write-only: stored encrypted and never returned.
3 attributes
access_tokenstringrequiredup to 8192 characterswrite-only, never returnedA system user access token with WhatsApp permissions.
app_secretstringrequiredup to 256 characterswrite-only, never returnedVerifies Meta's callback signatures.
verify_tokenstringrequired16 to 256 characterswrite-only, never returnedAny string you choose; Meta echoes it when it verifies the callback.
Returns
201 Connected
Response attributes
dataWhatsAppConnectionrequired17 attributes
idstringorg_idstringnamestringwaba_idstringThe WhatsApp Business Account id.
api_versionstringconfiguredbooleanCredentials are stored. False after a disconnect.
enabledbooleanFalse while paused: messages are not answered.
webhook_pathstringThe path of the callback URL to give Meta (on the API origin).
connected_viastringOne of
manualembeddedembedded_signupobject | nullEmbedded Signup only: the steps still to run after the connection was created, and why the last try stopped.
7 attributes
callback_originstringphone_number_idstring | nullcoexistencebooleanTrue when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.
pendingarray of stringNot run yet, or failed and to be retried. A step in neither
pendingnorskippedis done.skippedarray of stringRegistration is skipped when no
phone_number_idwas given or coexistence is true.failed_stepstring | nullOne of
subscriberegistersyncerrorstring | nullMeta's error code (
meta_<code>), never its message.
account_statusobject | nullThe latest
account_updateevent from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).3 attributes
eventstringdetailobjectatstringISO 8601 timestamp
review_statusstring | nullThe latest account review decision: APPROVED, REJECTED, PENDING.
health_updated_atstring | nullISO 8601 timestamptemplates_synced_atstring | nullISO 8601 timestampThe last template sync attempt.
templates_synced_ok_atstring | nullISO 8601 timestampThe last successful template sync.
templates_sync_errorstring | nullWhy the last template sync failed; null after a success.
numbersarray of WhatsAppNumber17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Travel WhatsApp",
"waba_id": "102938475610293",
"credentials": {
"access_token": "EAAG...",
"app_secret": "3f6c2a8e4b1d...",
"verify_token": "acme-verify-7d2e9b14c6a04f3e"
}
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"waba_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"api_version": "string",
"configured": true,
"enabled": true,
"webhook_path": "string",
"connected_via": "manual",
"embedded_signup": {
"callback_origin": "https://www.example.com",
"phone_number_id": "+14155550123",
"coexistence": true,
"pending": [
"subscribe"
],
"skipped": [
"register"
],
"failed_step": "subscribe",
"error": "string"
},
"account_status": {
"event": "string",
"detail": {
"key": "string"
},
"at": "2026-10-28T09:30:00.000Z"
},
"review_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"templates_synced_at": "2026-10-28T09:30:00.000Z",
"templates_synced_ok_at": "2026-10-28T09:30:00.000Z",
"templates_sync_error": "string",
"numbers": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}
}Update a WhatsApp connection
PATCH/api/integrations/whatsapp/connections/{id}
enabled: false pauses every number on the account; true resumes. New credentials are checked with Meta before they replace the stored ones. A disconnected account needs credentials to resume (409 whatsapp_credentials_required).
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Request body
namestringup to 100 charactersenabledbooleancredentialsobjectFrom your Meta app. Write-only: stored encrypted and never returned.
3 attributes
access_tokenstringrequiredup to 8192 characterswrite-only, never returnedA system user access token with WhatsApp permissions.
app_secretstringrequiredup to 256 characterswrite-only, never returnedVerifies Meta's callback signatures.
verify_tokenstringrequired16 to 256 characterswrite-only, never returnedAny string you choose; Meta echoes it when it verifies the callback.
Returns
200 Updated
Response attributes
dataWhatsAppConnectionrequired17 attributes
idstringorg_idstringnamestringwaba_idstringThe WhatsApp Business Account id.
api_versionstringconfiguredbooleanCredentials are stored. False after a disconnect.
enabledbooleanFalse while paused: messages are not answered.
webhook_pathstringThe path of the callback URL to give Meta (on the API origin).
connected_viastringOne of
manualembeddedembedded_signupobject | nullEmbedded Signup only: the steps still to run after the connection was created, and why the last try stopped.
7 attributes
callback_originstringphone_number_idstring | nullcoexistencebooleanTrue when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.
pendingarray of stringNot run yet, or failed and to be retried. A step in neither
pendingnorskippedis done.skippedarray of stringRegistration is skipped when no
phone_number_idwas given or coexistence is true.failed_stepstring | nullOne of
subscriberegistersyncerrorstring | nullMeta's error code (
meta_<code>), never its message.
account_statusobject | nullThe latest
account_updateevent from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).3 attributes
eventstringdetailobjectatstringISO 8601 timestamp
review_statusstring | nullThe latest account review decision: APPROVED, REJECTED, PENDING.
health_updated_atstring | nullISO 8601 timestamptemplates_synced_atstring | nullISO 8601 timestampThe last template sync attempt.
templates_synced_ok_atstring | nullISO 8601 timestampThe last successful template sync.
templates_sync_errorstring | nullWhy the last template sync failed; null after a success.
numbersarray of WhatsAppNumber17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400 Invalid body, or resuming would route a number to an assistant whose chat model cannot answer
- 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"enabled": true
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"waba_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"api_version": "string",
"configured": true,
"enabled": true,
"webhook_path": "string",
"connected_via": "manual",
"embedded_signup": {
"callback_origin": "https://www.example.com",
"phone_number_id": "+14155550123",
"coexistence": true,
"pending": [
"subscribe"
],
"skipped": [
"register"
],
"failed_step": "subscribe",
"error": "string"
},
"account_status": {
"event": "string",
"detail": {
"key": "string"
},
"at": "2026-10-28T09:30:00.000Z"
},
"review_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"templates_synced_at": "2026-10-28T09:30:00.000Z",
"templates_synced_ok_at": "2026-10-28T09:30:00.000Z",
"templates_sync_error": "string",
"numbers": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}
}Disconnect a WhatsApp account
DELETE/api/integrations/whatsapp/connections/{id}
Disconnects the account: messages stop being answered and the stored credentials are erased. Numbers, assignments and conversation history stay, so reconnecting with new credentials picks up where it left off.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 Disconnected
Response attributes
dataobjectrequired1 attribute
disconnectedbooleanrequiredOne of
true
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"disconnected": true
}
}Retry the remaining Embedded Signup steps
POST/api/integrations/whatsapp/connections/{id}/embedded/retry
Reruns the steps still pending (subscribe, register, sync); steps already done are not repeated, and each is safe to run again. Answers with the connection and, if a step failed again, which one. Admin role; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 The connection; embedded_signup.failed_step says which step to retry
Response attributes
dataWhatsAppConnectionrequired17 attributes
idstringorg_idstringnamestringwaba_idstringThe WhatsApp Business Account id.
api_versionstringconfiguredbooleanCredentials are stored. False after a disconnect.
enabledbooleanFalse while paused: messages are not answered.
webhook_pathstringThe path of the callback URL to give Meta (on the API origin).
connected_viastringOne of
manualembeddedembedded_signupobject | nullEmbedded Signup only: the steps still to run after the connection was created, and why the last try stopped.
7 attributes
callback_originstringphone_number_idstring | nullcoexistencebooleanTrue when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.
pendingarray of stringNot run yet, or failed and to be retried. A step in neither
pendingnorskippedis done.skippedarray of stringRegistration is skipped when no
phone_number_idwas given or coexistence is true.failed_stepstring | nullOne of
subscriberegistersyncerrorstring | nullMeta's error code (
meta_<code>), never its message.
account_statusobject | nullThe latest
account_updateevent from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).3 attributes
eventstringdetailobjectatstringISO 8601 timestamp
review_statusstring | nullThe latest account review decision: APPROVED, REJECTED, PENDING.
health_updated_atstring | nullISO 8601 timestamptemplates_synced_atstring | nullISO 8601 timestampThe last template sync attempt.
templates_synced_ok_atstring | nullISO 8601 timestampThe last successful template sync.
templates_sync_errorstring | nullWhy the last template sync failed; null after a success.
numbersarray of WhatsAppNumber17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_not_embedded_signup(connected by hand) orwhatsapp_disconnected - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/embedded/retry" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"waba_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"api_version": "string",
"configured": true,
"enabled": true,
"webhook_path": "string",
"connected_via": "manual",
"embedded_signup": {
"callback_origin": "https://www.example.com",
"phone_number_id": "+14155550123",
"coexistence": true,
"pending": [
"subscribe"
],
"skipped": [
"register"
],
"failed_step": "subscribe",
"error": "string"
},
"account_status": {
"event": "string",
"detail": {
"key": "string"
},
"at": "2026-10-28T09:30:00.000Z"
},
"review_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"templates_synced_at": "2026-10-28T09:30:00.000Z",
"templates_synced_ok_at": "2026-10-28T09:30:00.000Z",
"templates_sync_error": "string",
"numbers": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}
}Assign a WhatsApp number to an assistant
PUT/api/integrations/whatsapp/connections/{id}/numbers/{numberId}
Routes the number's WhatsApp messages to an assistant (assistant_id: null unassigns it), optionally pausing just this number. The assistant answers with its web chat model, so that model must be one chat supports.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
numberIdstringrequiredWhatsApp number id, from the connection's
numbers.
Request body
assistant_idstring | nullnot emptyAssistant id, or null to unassign. Omitted keeps the current one.
enabledbooleanFalse pauses this number only.
modestringOne of
livetestad_instructionsstring | nullup to 2000 charactersInstructions for people who arrive from a Click-to-WhatsApp ad, added to the assistant's prompt for those conversations only. Empty or null clears them; omitted keeps them.
Returns
200 Assigned
Response attributes
dataWhatsAppNumberrequired17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400 Invalid body, or the assistant's chat model has no chat adapter
- 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection); orassistant_archivedwhen the assistant is archived (restore it first; a number already assigned to it keeps it) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PUT "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/numbers/NUMBER_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true
}'{
"data": {
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
}Read an account's operator alert settings
GET/api/integrations/whatsapp/connections/{id}/operator-alerts
Who is alerted on WhatsApp when a chat in the organization (web chat or WhatsApp, live chats only) asks for a person, from which number and with which template. Off and empty until saved. Viewer role; needs an org-wide key.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 Settings
Response attributes
dataWhatsAppOperatorAlertsrequired8 attributes
connection_idstringenabledbooleannumber_idstring | nullThe account's number that sends the alerts.
template_namestring | nulltemplate_languagestring | nullstaff_numbersarray of stringE.164.
updated_atstring | nullISO 8601 timestampupdated_bystring | nullThe user or API key that saved them.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/operator-alerts" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"template_name": "string",
"template_language": "en",
"staff_numbers": [
"string"
],
"updated_at": "2026-10-28T09:30:00.000Z",
"updated_by": "string"
}
}Save an account's operator alert settings
PUT/api/integrations/whatsapp/connections/{id}/operator-alerts
Replaces the settings. number_id must be one of this account's numbers; the template must be an approved utility template on this account whose body takes at most 3 values (customer, assistant, chat link, in that order) and whose header and buttons take none; staff numbers are E.164, unique, at most 10. Turning alerts on needs all three. Each staff number gets one alert per request; requests more than 15 minutes old when first seen are not alerted; staff numbers that opted out of the sending number are skipped. Admin role; needs an org-wide key; audited.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Request body
enabledbooleanrequirednumber_idstring | nulltemplate_namestring | nulltemplate_languagestring | nullstaff_numbersarray of stringup to 10 items
Returns
200 Saved
Response attributes
dataWhatsAppOperatorAlertsrequired8 attributes
connection_idstringenabledbooleannumber_idstring | nullThe account's number that sends the alerts.
template_namestring | nulltemplate_languagestring | nullstaff_numbersarray of stringE.164.
updated_atstring | nullISO 8601 timestampupdated_bystring | nullThe user or API key that saved them.
- 400
whatsapp_alert_number_invalid,whatsapp_alert_template_invalid,whatsapp_alert_staff_numbers_invalid,whatsapp_alert_incomplete(with amessage), orinvalid_request - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PUT "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/operator-alerts" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'{
"data": {
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"template_name": "string",
"template_language": "en",
"staff_numbers": [
"string"
],
"updated_at": "2026-10-28T09:30:00.000Z",
"updated_by": "string"
}
}Send a test operator alert
POST/api/integrations/whatsapp/connections/{id}/operator-alerts/test
Sends the saved template once to each staff number now, with sample values and a link to Chats, whether alerts are on or off. Admin role; needs an org-wide key; audited.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 One result per staff number
Response attributes
dataobjectrequired1 attribute
resultsarray of object3 attributes
staff_numberstringstatusstringOne of
sentfailedskippederrorstring | nullMeta's code, or
whatsapp_contact_opted_outwhen skipped.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_disconnected,whatsapp_alert_incomplete(save a number, template and staff numbers first), orwhatsapp_alert_template_invalid - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/operator-alerts/test" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"results": [
{
"staff_number": "string",
"status": "sent",
"error": "string"
}
]
}
}Subscribe an account to its message callback
POST/api/integrations/whatsapp/connections/{id}/subscribe
Tells Meta to post this account's messages to its callback, then Meta verifies it with your verify_token. Use the public API origin with the connection's webhook_path (/public/whatsapp/webhooks/{id}); the older /whatsapp/webhooks/{id} path is also accepted. callback_url must be HTTPS with no query, fragment or credentials, at one of those paths (otherwise 400 whatsapp_public_https_webhook_required).
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Request body
callback_urlstringrequireduriup to 2048 characters
Returns
200 Subscribed
Response attributes
dataobjectrequired1 attribute
subscribedbooleanrequiredOne of
true
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/subscribe" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"callback_url": "https://example.com/hook"
}'{
"data": {
"subscribed": true
}
}Sync an account's phone numbers
POST/api/integrations/whatsapp/connections/{id}/sync
Fetches the account's current phone numbers from Meta, and each one's quality rating, messaging limit tier, status and display name review (a number Meta will not describe keeps what it had). New numbers arrive unassigned; existing ones keep their assistant.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 The account's numbers
Response attributes
dataarray of WhatsAppNumberrequired17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/sync" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}List an account's message templates
GET/api/integrations/whatsapp/connections/{id}/templates
The account's message templates as last synced from Meta (every hour, on a status callback for a template not seen yet, and on demand), any status. Needs an org-wide key.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 Templates
Response attributes
dataarray of WhatsAppTemplaterequired13 attributes
idstringconnection_idstringmeta_template_idstringnamestringlanguagestringcategorystringMARKETING, UTILITY or AUTHENTICATION.
statusstringAs Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...
componentsarray of objectMeta's template components, as given.
rejected_reasonstring | nullquality_scorestring | nullsynced_atstringISO 8601 timestampparametersobjectHow many values each part takes ({{1}} or named placeholders).
3 attributes
headerintegerbodyintegerbuttonsarray of integer
supportedbooleanFalse for templates with a media header or other parts this API cannot send.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"meta_template_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"language": "en",
"category": "string",
"status": "string",
"components": [
{}
],
"rejected_reason": "string",
"quality_score": "string",
"synced_at": "2026-10-28T09:30:00.000Z",
"parameters": {
"header": 1,
"body": 1,
"buttons": [
1
]
},
"supported": true
}
]
}Create a message template
POST/api/integrations/whatsapp/connections/{id}/templates
Submits a new text template to Meta for review and stores it as Meta answered, usually PENDING; approval or rejection arrives by Meta's status callback and the hourly sync. Placeholders are numbered ({{1}}, {{2}}...) and each needs an example. Meta may settle on a different category than the one asked. Audited. Admin; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Request body
namestringrequiredLowercase letters, digits and underscores.
languagestringrequiredTemplate language code, e.g.
en_USorhi.categorystringrequiredOne of
UTILITYMARKETINGheaderstringup to 60 charactersText header, at most one placeholder
{{1}}.header_examplestringup to 60 charactersRequired when the header has a placeholder.
bodystringrequiredup to 1024 charactersWith
{{1}}to{{n}}in order, none skipped.body_examplesarray of stringOne non-empty sample value per body placeholder, in order.
buttonsarray of objectup to 10 itemsQuick replies and at most 2 URL buttons.
4 attributes
typestringrequiredOne of
QUICK_REPLYURLtextstringrequiredup to 25 charactersurlstringup to 2000 charactersURL buttons: https, optionally ending in
{{1}}.examplestringup to 2000 charactersRequired when the URL ends in
{{1}}.
Returns
201 Submitted
Response attributes
dataWhatsAppTemplaterequired13 attributes
idstringconnection_idstringmeta_template_idstringnamestringlanguagestringcategorystringMARKETING, UTILITY or AUTHENTICATION.
statusstringAs Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...
componentsarray of objectMeta's template components, as given.
rejected_reasonstring | nullquality_scorestring | nullsynced_atstringISO 8601 timestampparametersobjectHow many values each part takes ({{1}} or named placeholders).
3 attributes
headerintegerbodyintegerbuttonsarray of integer
supportedbooleanFalse for templates with a media header or other parts this API cannot send.
- 400 Invalid body, placeholders not numbered in order, or missing examples
- 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_template_exists(same name and language) orwhatsapp_disconnected - 422 Meta refused it:
meta_<code> - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "front_desk",
"language": "en",
"category": "UTILITY",
"body": "string"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"meta_template_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"language": "en",
"category": "string",
"status": "string",
"components": [
{}
],
"rejected_reason": "string",
"quality_score": "string",
"synced_at": "2026-10-28T09:30:00.000Z",
"parameters": {
"header": 1,
"body": 1,
"buttons": [
1
]
},
"supported": true
}
}Delete a message template
DELETE/api/integrations/whatsapp/connections/{id}/templates/{name}
Deletes the template at Meta, every language of the name, then here. Messages already queued with it fail when sent. Audited. Admin; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
namestringrequiredTemplate name.
Returns
200 Deleted
Response attributes
dataobjectrequired2 attributes
namestringdeletedintegerHow many languages were removed here.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found(no such connection) orwhatsapp_template_not_found - 409
whatsapp_disconnected - 422 Meta refused it:
meta_<code> - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates/NAME" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"name": "Front desk",
"deleted": 1
}
}Sync an account's message templates
POST/api/integrations/whatsapp/connections/{id}/templates/sync
Fetches the account's templates from Meta now: new ones are added, changed ones updated, and ones deleted in Meta removed. Admin; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
idstringrequiredWhatsApp connection id.
Returns
200 Templates
Response attributes
dataarray of WhatsAppTemplaterequired13 attributes
idstringconnection_idstringmeta_template_idstringnamestringlanguagestringcategorystringMARKETING, UTILITY or AUTHENTICATION.
statusstringAs Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...
componentsarray of objectMeta's template components, as given.
rejected_reasonstring | nullquality_scorestring | nullsynced_atstringISO 8601 timestampparametersobjectHow many values each part takes ({{1}} or named placeholders).
3 attributes
headerintegerbodyintegerbuttonsarray of integer
supportedbooleanFalse for templates with a media header or other parts this API cannot send.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates/sync" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"meta_template_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"language": "en",
"category": "string",
"status": "string",
"components": [
{}
],
"rejected_reason": "string",
"quality_score": "string",
"synced_at": "2026-10-28T09:30:00.000Z",
"parameters": {
"header": 1,
"body": 1,
"buttons": [
1
]
},
"supported": true
}
]
}Connect an account through Embedded Signup
POST/api/integrations/whatsapp/connections/embedded
Exchanges the code Meta's Embedded Signup returned for a business token, creates the connection (same uniqueness rules as connecting by hand; Meta signs its callbacks with the platform app's secret), then subscribes the account to its callback, registers the number (with a two-step verification PIN kept in the encrypted credentials) and syncs numbers. A failed exchange or creation creates nothing (422 with step: exchange or create; 400 whatsapp_unknown_number for a phone_number_id the account does not list). The organization's own disconnected connection for the same account is taken over in place. A step after creation that fails keeps the connection and the other steps still run: the response is still 201 and embedded_signup names the first failed step and Meta's error code; retry with .../embedded/retry. Admin role; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Request body
codestringrequiredup to 2048 characterswrite-only, never returnedFrom Meta's Embedded Signup popup.
waba_idstringrequiredFrom the popup's session info.
coexistencebooleanSet true for WhatsApp Business app onboarding. Keeps the app's existing registration and skips Cloud API registration, including on retries.
Default
falsephone_number_idstringThe number to register, from the popup's session info. Omitted: registration is skipped.
namestringup to 100 charactersYour label; defaults to
WhatsApp <waba_id>.callback_urlstringrequireduriup to 2048 charactersThe public API origin (or it plus
/public/whatsapp/webhooks): HTTPS, no query, fragment or credentials. The connection's own webhook path is added to it.
Returns
201 The connection; embedded_signup.failed_step says which step to retry
Response attributes
dataWhatsAppConnectionrequired17 attributes
idstringorg_idstringnamestringwaba_idstringThe WhatsApp Business Account id.
api_versionstringconfiguredbooleanCredentials are stored. False after a disconnect.
enabledbooleanFalse while paused: messages are not answered.
webhook_pathstringThe path of the callback URL to give Meta (on the API origin).
connected_viastringOne of
manualembeddedembedded_signupobject | nullEmbedded Signup only: the steps still to run after the connection was created, and why the last try stopped.
7 attributes
callback_originstringphone_number_idstring | nullcoexistencebooleanTrue when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.
pendingarray of stringNot run yet, or failed and to be retried. A step in neither
pendingnorskippedis done.skippedarray of stringRegistration is skipped when no
phone_number_idwas given or coexistence is true.failed_stepstring | nullOne of
subscriberegistersyncerrorstring | nullMeta's error code (
meta_<code>), never its message.
account_statusobject | nullThe latest
account_updateevent from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).3 attributes
eventstringdetailobjectatstringISO 8601 timestamp
review_statusstring | nullThe latest account review decision: APPROVED, REJECTED, PENDING.
health_updated_atstring | nullISO 8601 timestamptemplates_synced_atstring | nullISO 8601 timestampThe last template sync attempt.
templates_synced_ok_atstring | nullISO 8601 timestampThe last successful template sync.
templates_sync_errorstring | nullWhy the last template sync failed; null after a success.
numbersarray of WhatsAppNumber17 attributes
idstringconnection_idstringphone_number_idstringdisplay_phone_numberstringverified_namestring | nullassistant_idstring | nullenabledbooleanmodestringOne of
livetestad_instructionsstring | nullInstructions for people arriving from an ad.
failed_repliesintegerList only: replies that could not be sent.
failed_turnsintegerList only: incoming messages the assistant failed to answer.
quality_ratingstring | nullAs Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.
messaging_limit_tierstring | nullTIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...
statusstring | nullCONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...
name_statusstring | nullDisplay name review: APPROVED, PENDING_REVIEW, DECLINED...
health_updated_atstring | nullISO 8601 timestampnext_stepstringList only: the one thing to do next for this number, most blocking first.
One of
resolve_restrictionregister_numberverify_display_namedisplay_name_in_reviewraise_qualitynone
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_embedded_signup_disabled(the platform app is not configured) orwhatsapp_already_connected - 422 Meta refused the code exchange or the token:
{error: meta_<code>, step: exchange | create, message}, the sameerrorcodes as the other WhatsApp routes' 422s, withstepbeside it - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/embedded" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "string",
"waba_id": "102938475610293",
"callback_url": "https://example.com/hook"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"waba_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"api_version": "string",
"configured": true,
"enabled": true,
"webhook_path": "string",
"connected_via": "manual",
"embedded_signup": {
"callback_origin": "https://www.example.com",
"phone_number_id": "+14155550123",
"coexistence": true,
"pending": [
"subscribe"
],
"skipped": [
"register"
],
"failed_step": "subscribe",
"error": "string"
},
"account_status": {
"event": "string",
"detail": {
"key": "string"
},
"at": "2026-10-28T09:30:00.000Z"
},
"review_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"templates_synced_at": "2026-10-28T09:30:00.000Z",
"templates_synced_ok_at": "2026-10-28T09:30:00.000Z",
"templates_sync_error": "string",
"numbers": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_number_id": "+14155550123",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"enabled": true,
"mode": "live",
"ad_instructions": "You answer enquiries for Acme Travel.",
"failed_replies": 1,
"failed_turns": 1,
"quality_rating": "string",
"messaging_limit_tier": "string",
"status": "string",
"name_status": "string",
"health_updated_at": "2026-10-28T09:30:00.000Z",
"next_step": "resolve_restriction"
}
]
}
}Record or withdraw marketing consent
PUT/api/integrations/whatsapp/contacts/{contactId}/marketing-opt-in
Records that the person agreed to marketing templates (opted_in: true) and where that consent came from, or withdraws it. Audited. It does not undo a STOP: an opted-out contact gets no template until they send START. Member role; needs an org-wide key.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
contactIdstringrequiredWhatsApp contact id.
Request body
opted_inbooleanrequiredsourcestringrequiredup to 200 charactersWhere the consent came from.
Returns
200 Contact
Response attributes
dataWhatsAppContactrequired12 attributes
idstringnumber_idstringwa_idstringThe sender's WhatsApp number.
profile_namestring | nullSender-set, never verified.
first_inbound_atstringISO 8601 timestamplast_inbound_atstringISO 8601 timestampopted_out_atstring | nullISO 8601 timestampSet by STOP; cleared by START.
opted_out_sourcestring | nullmarketing_opt_in_atstring | nullISO 8601 timestampmarketing_opt_in_sourcestring | nullmarketing_opt_in_bystring | nullThe user or API key that recorded it.
marketing_opt_in_by_namestring | nullThe recording user's name (or email); null when an API key recorded it.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PUT "https://api.brightshoal.com/api/integrations/whatsapp/contacts/CONTACT_ID/marketing-opt-in" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"opted_in": true,
"source": "string"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"wa_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"profile_name": "string",
"first_inbound_at": "2026-10-28T09:30:00.000Z",
"last_inbound_at": "2026-10-28T09:30:00.000Z",
"opted_out_at": "2026-10-28T09:30:00.000Z",
"opted_out_source": "string",
"marketing_opt_in_at": "2026-10-28T09:30:00.000Z",
"marketing_opt_in_source": "string",
"marketing_opt_in_by": "string",
"marketing_opt_in_by_name": "string"
}
}Get a conversation's WhatsApp contact
GET/api/integrations/whatsapp/conversations/{conversationId}/contact
The sender's contact on this number: when they wrote, whether they opted out (STOP), and any recorded marketing opt-in with the name of the user who recorded it. data is null for a sender not recorded yet. Viewer role.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
conversationIdstringrequiredWhatsApp conversation id.
Returns
200 Contact
Response attributes
dataWhatsAppContact | nullrequiredOne of 2 shapes
WhatsAppContact
idstringnumber_idstringwa_idstringThe sender's WhatsApp number.
profile_namestring | nullSender-set, never verified.
first_inbound_atstringISO 8601 timestamplast_inbound_atstringISO 8601 timestampopted_out_atstring | nullISO 8601 timestampSet by STOP; cleared by START.
opted_out_sourcestring | nullmarketing_opt_in_atstring | nullISO 8601 timestampmarketing_opt_in_sourcestring | nullmarketing_opt_in_bystring | nullThe user or API key that recorded it.
marketing_opt_in_by_namestring | nullThe recording user's name (or email); null when an API key recorded it.
Option 2
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/contact" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"wa_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"profile_name": "string",
"first_inbound_at": "2026-10-28T09:30:00.000Z",
"last_inbound_at": "2026-10-28T09:30:00.000Z",
"opted_out_at": "2026-10-28T09:30:00.000Z",
"opted_out_source": "string",
"marketing_opt_in_at": "2026-10-28T09:30:00.000Z",
"marketing_opt_in_source": "string",
"marketing_opt_in_by": "string",
"marketing_opt_in_by_name": "string"
}
}Delivery state of a conversation's messages
GET/api/integrations/whatsapp/conversations/{conversationId}/deliveries
Per message sent on WhatsApp in this conversation: its delivery state (the least advanced of the parts it was sent as; a failed part makes it failed), Meta's error code when it failed, when it last changed and how many parts it was sent as. Messages never sent on WhatsApp are not listed. Viewer role; a project key reaches its own project's conversations.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
conversationIdstringrequiredWhatsApp conversation id.
Returns
200 Deliveries
Response attributes
dataarray of objectrequired5 attributes
message_idstringstatusstringOne of
failedunknownpendingsendingsentdeliveredreaderrorstring | nullmeta_<code>when failed.updated_atstringISO 8601 timestamppartsinteger
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/deliveries" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"message_id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "failed",
"error": "string",
"updated_at": "2026-10-28T09:30:00.000Z",
"parts": 1
}
]
}Send a template message
POST/api/integrations/whatsapp/conversations/{conversationId}/template
Sends an approved template to the conversation's sender. Works when the 24-hour service window has closed (that is what templates are for) and needs no takeover; the assistant keeps answering their reply unless the chat is taken over. The rendered text is added to the transcript as an operator message carrying the template; the delivery worker sends it. If the sender's conversation has ended, a new conversation is started for the same number and sender. Refused for a contact who opted out (STOP), and for a marketing template without a recorded marketing opt-in. Member role; a project key reaches its own project's conversations.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
conversationIdstringrequiredWhatsApp conversation id.
Request body
namestringrequiredup to 512 characterslanguagestringrequiredup to 32 charactersTemplate language code, e.g.
en_US.parametersobjectValues for the template's placeholders, in order: as many as the template's
parameterscounts say. Each is non-empty text without new lines, tabs or more than four spaces in a row; header values up to 60 characters, body up to 1,024, button up to 2,000.3 attributes
headerarray of stringbodyarray of stringbuttonsarray of array of stringbuttons[i]fills the i-th button (only URL buttons take a value).
agentobjectWho is sending, for an API key. A signed-in user is recorded as themselves.
3 attributes
idstringemailstringemailnamestring
client_message_idstringup to 200 charactersSet per send; a retry with the same id returns the original instead of sending again.
Returns
201 Queued
Response attributes
dataobjectrequired6 attributes
idstringThe transcript message id.
conversation_idstringWhere it was added: a new conversation if the old one had ended.
rolestringOne of
agentcontentstringThe rendered template text.
seqintegercreated_atstringISO 8601 timestamp
- 400 Invalid body, parameter counts that do not match the template, or a template with a media header
- 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found(no such WhatsApp conversation in scope) orwhatsapp_template_not_found - 409
whatsapp_template_not_approved,whatsapp_contact_opted_out,whatsapp_marketing_opt_in_required,whatsapp_disconnectedorclient_message_id_reused - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/template" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"language": "en"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"role": "agent",
"content": "Hi, can I book a trip to Lisbon in May?",
"seq": 1,
"created_at": "2026-10-28T09:30:00.000Z"
}
}List the templates a conversation can be sent
GET/api/integrations/whatsapp/conversations/{conversationId}/templates
The approved templates of the account the conversation's number belongs to, with how many values each part takes. Member role; a project key sees its own project's conversations.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
conversationIdstringrequiredWhatsApp conversation id.
Returns
200 Approved templates
Response attributes
dataarray of WhatsAppTemplaterequired13 attributes
idstringconnection_idstringmeta_template_idstringnamestringlanguagestringcategorystringMARKETING, UTILITY or AUTHENTICATION.
statusstringAs Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...
componentsarray of objectMeta's template components, as given.
rejected_reasonstring | nullquality_scorestring | nullsynced_atstringISO 8601 timestampparametersobjectHow many values each part takes ({{1}} or named placeholders).
3 attributes
headerintegerbodyintegerbuttonsarray of integer
supportedbooleanFalse for templates with a media header or other parts this API cannot send.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such WhatsApp conversation in scope - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/templates" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"meta_template_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"language": "en",
"category": "string",
"status": "string",
"components": [
{}
],
"rejected_reason": "string",
"quality_score": "string",
"synced_at": "2026-10-28T09:30:00.000Z",
"parameters": {
"header": 1,
"body": 1,
"buttons": [
1
]
},
"supported": true
}
]
}Embedded Signup settings
GET/api/integrations/whatsapp/embedded-signup
What the console needs to open Meta's Embedded Signup: the platform app id, its configuration id and the Graph API version. enabled is false (and the ids null) unless the platform app is configured. The app secret is never returned. Admin role; needs an org-wide key.
Secret API key, org-wide (not pinned to a project). How it works
Returns
200 Settings
Response attributes
dataobjectrequired4 attributes
enabledbooleanapp_idstring | nullconfig_idstring | nullgraph_api_versionstring
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404
not_found: no such connection or number in this organization - 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/embedded-signup" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"enabled": true,
"app_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"config_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"graph_api_version": "string"
}
}List a number's campaign links
GET/api/integrations/whatsapp/numbers/{numberId}/links
The number's campaign links that are not archived, newest first, each with its wa.me URL and how many WhatsApp conversations it started. Needs an org-wide key.
Secret API key, org-wide (not pinned to a project). How it works
Path parameters
numberIdstringrequiredWhatsApp number id, from the connection's
numbers.
Returns
200 Links
Response attributes
dataarray of WhatsAppLinkrequired14 attributes
idstringnumber_idstringnamestringcodestring8 characters starting with C.
prefillstring | nullutm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullurlstringuriThe wa.me link to share or print as a QR code.
created_bystring | nullThe user or API key that created it.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampconversationsintegerList only: WhatsApp conversations this link started.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404 No such number in your organization
- 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/numbers/NUMBER_ID/links" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"code": "string",
"prefill": "string",
"utm_source": "string",
"utm_medium": "string",
"utm_campaign": "string",
"url": "https://example.com/hook",
"created_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"archived_at": "2026-10-28T09:30:00.000Z",
"conversations": 1
}
]
}Create a campaign link
POST/api/integrations/whatsapp/numbers/{numberId}/links
A named link that opens WhatsApp to this number with prefill (default "Hi") followed by "(ref CODE)". A conversation whose first message carries the code records the link and its utm tags as its first touch (attribution.first.whatsapp_link_id). Admin, org-wide key; audited.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
numberIdstringrequiredWhatsApp number id, from the connection's
numbers.
Request body
namestringrequiredup to 100 charactersprefillstring | nullup to 200 charactersThe message WhatsApp opens with.
utm_sourcestring | nullup to 100 charactersutm_mediumstring | nullup to 100 charactersutm_campaignstring | nullup to 100 characters
Returns
201 Created
Response attributes
dataWhatsAppLinkrequired14 attributes
idstringnumber_idstringnamestringcodestring8 characters starting with C.
prefillstring | nullutm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullurlstringuriThe wa.me link to share or print as a QR code.
created_bystring | nullThe user or API key that created it.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampconversationsintegerList only: WhatsApp conversations this link started.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404 No such number in your organization
- 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/numbers/NUMBER_ID/links" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"code": "string",
"prefill": "string",
"utm_source": "string",
"utm_medium": "string",
"utm_campaign": "string",
"url": "https://example.com/hook",
"created_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"archived_at": "2026-10-28T09:30:00.000Z",
"conversations": 1
}
}Update a campaign link
PATCH/api/integrations/whatsapp/numbers/{numberId}/links/{linkId}
Changes its name, prefill or tags; the code stays. Null or empty clears an optional field. Admin; audited.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
numberIdstringrequiredWhatsApp number id, from the connection's
numbers.linkIdstringrequiredCampaign link id (
wal_...).
Request body
namestringup to 100 charactersprefillstring | nullup to 200 charactersThe message WhatsApp opens with.
utm_sourcestring | nullup to 100 charactersutm_mediumstring | nullup to 100 charactersutm_campaignstring | nullup to 100 characters
Returns
200 Updated
Response attributes
dataWhatsAppLinkrequired14 attributes
idstringnumber_idstringnamestringcodestring8 characters starting with C.
prefillstring | nullutm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullurlstringuriThe wa.me link to share or print as a QR code.
created_bystring | nullThe user or API key that created it.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampconversationsintegerList only: WhatsApp conversations this link started.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404 No such link on this number
- 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/integrations/whatsapp/numbers/NUMBER_ID/links/LINK_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"prefill": "string"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"code": "string",
"prefill": "string",
"utm_source": "string",
"utm_medium": "string",
"utm_campaign": "string",
"url": "https://example.com/hook",
"created_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"archived_at": "2026-10-28T09:30:00.000Z",
"conversations": 1
}
}Archive a campaign link
DELETE/api/integrations/whatsapp/numbers/{numberId}/links/{linkId}
Hides it from the list. Its code still resolves, so a printed QR code keeps attributing, and conversations it started keep their attribution. Admin; audited.
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Path parameters
numberIdstringrequiredWhatsApp number id, from the connection's
numbers.linkIdstringrequiredCampaign link id (
wal_...).
Returns
200 Archived
Response attributes
dataWhatsAppLinkrequired14 attributes
idstringnumber_idstringnamestringcodestring8 characters starting with C.
prefillstring | nullutm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullurlstringuriThe wa.me link to share or print as a QR code.
created_bystring | nullThe user or API key that created it.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampconversationsintegerList only: WhatsApp conversations this link started.
- 400
invalid_request: the body failed validation - 403
org_scope_required(needs an org-wide key; project keys get 403) or the role is too low - 404 No such link on this number
- 409
whatsapp_already_connected,whatsapp_credentials_required,whatsapp_disconnected, or on syncwhatsapp_number_already_connected(a number already belongs to another connection) - 422 Meta refused the request (
meta_<Meta error code>, ormeta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/integrations/whatsapp/numbers/NUMBER_ID/links/LINK_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"code": "string",
"prefill": "string",
"utm_source": "string",
"utm_medium": "string",
"utm_campaign": "string",
"url": "https://example.com/hook",
"created_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"archived_at": "2026-10-28T09:30:00.000Z",
"conversations": 1
}
}List project WhatsApp numbers and approved templates
GET/api/integrations/whatsapp/numbers/templates
Viewer read for reminder pickers. Enabled live numbers on enabled accounts with stored credentials, assigned to an assistant in this project. Templates are the last synced approved versions; supported indicates whether this API can send them. Unknown or inaccessible projects return an empty list. No provider request is made.
Secret API key, org-wide (not pinned to a project). How it works
Query parameters
project_idstringRequired for an org-wide key; a project key defaults to its project.
Returns
200 Connected numbers with approved templates
Response attributes
dataobjectrequired1 attribute
dataarray of WhatsAppNumberTemplatesrequired6 attributes
idstringrequiredconnection_idstringrequireddisplay_phone_numberstringrequiredverified_namestring | nullrequiredassistant_idstringrequiredtemplatesarray of objectrequired8 attributes
idstringrequirednamestringrequiredlanguagestringrequiredcategorystringrequiredbody_previewstringrequiredBody text with placeholders intact.
variablesobjectrequiredPlaceholder names in parameter order, per component; buttons are indexed by button position.
3 attributes
headerarray of stringrequiredbodyarray of stringrequiredbuttonsarray of array of stringrequired
parametersobjectrequired3 attributes
headerintegerrequiredbodyintegerrequiredbuttonsarray of integerrequired
supportedbooleanrequired
- 400 Project required or conflicts with the project key
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations/whatsapp/numbers/templates" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"data": [
{
"id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"connection_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"display_phone_number": "+14155550123",
"verified_name": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"templates": [
{
"id": {},
"name": {},
"language": {},
"category": {},
"body_preview": {},
"variables": {},
"parameters": {},
"supported": {}
}
]
}
]
}
}