BrightshoalDocsOpen console
MenuWhatsApp

API reference

WhatsApp

Connect a WhatsApp Business Account from Meta and assign its numbers to assistants.

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 WhatsAppConnectionrequired

    17 attributes
    • idstring

    • org_idstring

    • namestring

    • waba_idstring

      The WhatsApp Business Account id.

    • api_versionstring

    • configuredboolean

      Credentials are stored. False after a disconnect.

    • enabledboolean

      False while paused: messages are not answered.

    • webhook_pathstring

      The path of the callback URL to give Meta (on the API origin).

    • connected_viastring

      One of manual embedded

    • embedded_signupobject | null

      Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.

      7 attributes
      • callback_originstring

      • phone_number_idstring | null

      • coexistenceboolean

        True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.

      • pendingarray of string

        Not run yet, or failed and to be retried. A step in neither pending nor skipped is done.

      • skippedarray of string

        Registration is skipped when no phone_number_id was given or coexistence is true.

      • failed_stepstring | null

        One of subscribe register sync

      • errorstring | null

        Meta's error code (meta_<code>), never its message.

    • account_statusobject | null

      The latest account_update event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).

      3 attributes
      • eventstring

      • detailobject

      • atstringISO 8601 timestamp

    • review_statusstring | null

      The latest account review decision: APPROVED, REJECTED, PENDING.

    • health_updated_atstring | nullISO 8601 timestamp

    • templates_synced_atstring | nullISO 8601 timestamp

      The last template sync attempt.

    • templates_synced_ok_atstring | nullISO 8601 timestamp

      The last successful template sync.

    • templates_sync_errorstring | null

      Why the last template sync failed; null after a success.

    • numbersarray of WhatsAppNumber

      17 attributes
      • idstring

      • connection_idstring

      • phone_number_idstring

      • display_phone_numberstring

      • verified_namestring | null

      • assistant_idstring | null

      • enabledboolean

      • modestring

        One of live test

      • ad_instructionsstring | null

        Instructions for people arriving from an ad.

      • failed_repliesinteger

        List only: replies that could not be sent.

      • failed_turnsinteger

        List only: incoming messages the assistant failed to answer.

      • quality_ratingstring | null

        As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

      • messaging_limit_tierstring | null

        TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

      • statusstring | null

        CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

      • name_statusstring | null

        Display name review: APPROVED, PENDING_REVIEW, DECLINED...

      • health_updated_atstring | nullISO 8601 timestamp

      • next_stepstring

        List only: the one thing to do next for this number, most blocking first.

        One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/connections
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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 characters

    Your label for the account.

  • waba_idstringrequired

    The WhatsApp Business Account id (digits).

  • api_versionstring

    Graph API version.

    Default "v25.0"

  • credentialsobjectrequired

    From your Meta app. Write-only: stored encrypted and never returned.

    3 attributes
    • access_tokenstringrequiredup to 8192 characterswrite-only, never returned

      A system user access token with WhatsApp permissions.

    • app_secretstringrequiredup to 256 characterswrite-only, never returned

      Verifies Meta's callback signatures.

    • verify_tokenstringrequired16 to 256 characterswrite-only, never returned

      Any string you choose; Meta echoes it when it verifies the callback.

Returns

201 Connected

Response attributes
  • dataWhatsAppConnectionrequired

    17 attributes
    • idstring

    • org_idstring

    • namestring

    • waba_idstring

      The WhatsApp Business Account id.

    • api_versionstring

    • configuredboolean

      Credentials are stored. False after a disconnect.

    • enabledboolean

      False while paused: messages are not answered.

    • webhook_pathstring

      The path of the callback URL to give Meta (on the API origin).

    • connected_viastring

      One of manual embedded

    • embedded_signupobject | null

      Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.

      7 attributes
      • callback_originstring

      • phone_number_idstring | null

      • coexistenceboolean

        True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.

      • pendingarray of string

        Not run yet, or failed and to be retried. A step in neither pending nor skipped is done.

      • skippedarray of string

        Registration is skipped when no phone_number_id was given or coexistence is true.

      • failed_stepstring | null

        One of subscribe register sync

      • errorstring | null

        Meta's error code (meta_<code>), never its message.

    • account_statusobject | null

      The latest account_update event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).

      3 attributes
      • eventstring

      • detailobject

      • atstringISO 8601 timestamp

    • review_statusstring | null

      The latest account review decision: APPROVED, REJECTED, PENDING.

    • health_updated_atstring | nullISO 8601 timestamp

    • templates_synced_atstring | nullISO 8601 timestamp

      The last template sync attempt.

    • templates_synced_ok_atstring | nullISO 8601 timestamp

      The last successful template sync.

    • templates_sync_errorstring | null

      Why the last template sync failed; null after a success.

    • numbersarray of WhatsAppNumber

      17 attributes
      • idstring

      • connection_idstring

      • phone_number_idstring

      • display_phone_numberstring

      • verified_namestring | null

      • assistant_idstring | null

      • enabledboolean

      • modestring

        One of live test

      • ad_instructionsstring | null

        Instructions for people arriving from an ad.

      • failed_repliesinteger

        List only: replies that could not be sent.

      • failed_turnsinteger

        List only: incoming messages the assistant failed to answer.

      • quality_ratingstring | null

        As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

      • messaging_limit_tierstring | null

        TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

      • statusstring | null

        CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

      • name_statusstring | null

        Display name review: APPROVED, PENDING_REVIEW, DECLINED...

      • health_updated_atstring | nullISO 8601 timestamp

      • next_stepstring

        List only: the one thing to do next for this number, most blocking first.

        One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections
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"
  }
}'
Response 201
{
  "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

  • idstringrequired

    WhatsApp connection id.

Request body

  • namestringup to 100 characters

  • enabledboolean

  • credentialsobject

    From your Meta app. Write-only: stored encrypted and never returned.

    3 attributes
    • access_tokenstringrequiredup to 8192 characterswrite-only, never returned

      A system user access token with WhatsApp permissions.

    • app_secretstringrequiredup to 256 characterswrite-only, never returned

      Verifies Meta's callback signatures.

    • verify_tokenstringrequired16 to 256 characterswrite-only, never returned

      Any string you choose; Meta echoes it when it verifies the callback.

Returns

200 Updated

Response attributes
  • dataWhatsAppConnectionrequired

    17 attributes
    • idstring

    • org_idstring

    • namestring

    • waba_idstring

      The WhatsApp Business Account id.

    • api_versionstring

    • configuredboolean

      Credentials are stored. False after a disconnect.

    • enabledboolean

      False while paused: messages are not answered.

    • webhook_pathstring

      The path of the callback URL to give Meta (on the API origin).

    • connected_viastring

      One of manual embedded

    • embedded_signupobject | null

      Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.

      7 attributes
      • callback_originstring

      • phone_number_idstring | null

      • coexistenceboolean

        True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.

      • pendingarray of string

        Not run yet, or failed and to be retried. A step in neither pending nor skipped is done.

      • skippedarray of string

        Registration is skipped when no phone_number_id was given or coexistence is true.

      • failed_stepstring | null

        One of subscribe register sync

      • errorstring | null

        Meta's error code (meta_<code>), never its message.

    • account_statusobject | null

      The latest account_update event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).

      3 attributes
      • eventstring

      • detailobject

      • atstringISO 8601 timestamp

    • review_statusstring | null

      The latest account review decision: APPROVED, REJECTED, PENDING.

    • health_updated_atstring | nullISO 8601 timestamp

    • templates_synced_atstring | nullISO 8601 timestamp

      The last template sync attempt.

    • templates_synced_ok_atstring | nullISO 8601 timestamp

      The last successful template sync.

    • templates_sync_errorstring | null

      Why the last template sync failed; null after a success.

    • numbersarray of WhatsAppNumber

      17 attributes
      • idstring

      • connection_idstring

      • phone_number_idstring

      • display_phone_numberstring

      • verified_namestring | null

      • assistant_idstring | null

      • enabledboolean

      • modestring

        One of live test

      • ad_instructionsstring | null

        Instructions for people arriving from an ad.

      • failed_repliesinteger

        List only: replies that could not be sent.

      • failed_turnsinteger

        List only: incoming messages the assistant failed to answer.

      • quality_ratingstring | null

        As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

      • messaging_limit_tierstring | null

        TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

      • statusstring | null

        CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

      • name_statusstring | null

        Display name review: APPROVED, PENDING_REVIEW, DECLINED...

      • health_updated_atstring | nullISO 8601 timestamp

      • next_stepstring

        List only: the one thing to do next for this number, most blocking first.

        One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
PATCH /api/integrations/whatsapp/connections/{id}
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
}'
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 Disconnected

Response attributes
  • dataobjectrequired

    1 attribute
    • disconnectedbooleanrequired

      One 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
DELETE /api/integrations/whatsapp/connections/{id}
curl -X DELETE "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 The connection; embedded_signup.failed_step says which step to retry

Response attributes
  • dataWhatsAppConnectionrequired

    17 attributes
    • idstring

    • org_idstring

    • namestring

    • waba_idstring

      The WhatsApp Business Account id.

    • api_versionstring

    • configuredboolean

      Credentials are stored. False after a disconnect.

    • enabledboolean

      False while paused: messages are not answered.

    • webhook_pathstring

      The path of the callback URL to give Meta (on the API origin).

    • connected_viastring

      One of manual embedded

    • embedded_signupobject | null

      Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.

      7 attributes
      • callback_originstring

      • phone_number_idstring | null

      • coexistenceboolean

        True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.

      • pendingarray of string

        Not run yet, or failed and to be retried. A step in neither pending nor skipped is done.

      • skippedarray of string

        Registration is skipped when no phone_number_id was given or coexistence is true.

      • failed_stepstring | null

        One of subscribe register sync

      • errorstring | null

        Meta's error code (meta_<code>), never its message.

    • account_statusobject | null

      The latest account_update event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).

      3 attributes
      • eventstring

      • detailobject

      • atstringISO 8601 timestamp

    • review_statusstring | null

      The latest account review decision: APPROVED, REJECTED, PENDING.

    • health_updated_atstring | nullISO 8601 timestamp

    • templates_synced_atstring | nullISO 8601 timestamp

      The last template sync attempt.

    • templates_synced_ok_atstring | nullISO 8601 timestamp

      The last successful template sync.

    • templates_sync_errorstring | null

      Why the last template sync failed; null after a success.

    • numbersarray of WhatsAppNumber

      17 attributes
      • idstring

      • connection_idstring

      • phone_number_idstring

      • display_phone_numberstring

      • verified_namestring | null

      • assistant_idstring | null

      • enabledboolean

      • modestring

        One of live test

      • ad_instructionsstring | null

        Instructions for people arriving from an ad.

      • failed_repliesinteger

        List only: replies that could not be sent.

      • failed_turnsinteger

        List only: incoming messages the assistant failed to answer.

      • quality_ratingstring | null

        As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

      • messaging_limit_tierstring | null

        TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

      • statusstring | null

        CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

      • name_statusstring | null

        Display name review: APPROVED, PENDING_REVIEW, DECLINED...

      • health_updated_atstring | nullISO 8601 timestamp

      • next_stepstring

        List only: the one thing to do next for this number, most blocking first.

        One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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) or whatsapp_disconnected
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/embedded/retry
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/embedded/retry" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

  • numberIdstringrequired

    WhatsApp number id, from the connection's numbers.

Request body

  • assistant_idstring | nullnot empty

    Assistant id, or null to unassign. Omitted keeps the current one.

  • enabledboolean

    False pauses this number only.

  • modestring

    One of live test

  • ad_instructionsstring | nullup to 2000 characters

    Instructions 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
  • dataWhatsAppNumberrequired

    17 attributes
    • idstring

    • connection_idstring

    • phone_number_idstring

    • display_phone_numberstring

    • verified_namestring | null

    • assistant_idstring | null

    • enabledboolean

    • modestring

      One of live test

    • ad_instructionsstring | null

      Instructions for people arriving from an ad.

    • failed_repliesinteger

      List only: replies that could not be sent.

    • failed_turnsinteger

      List only: incoming messages the assistant failed to answer.

    • quality_ratingstring | null

      As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

    • messaging_limit_tierstring | null

      TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

    • statusstring | null

      CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

    • name_statusstring | null

      Display name review: APPROVED, PENDING_REVIEW, DECLINED...

    • health_updated_atstring | nullISO 8601 timestamp

    • next_stepstring

      List only: the one thing to do next for this number, most blocking first.

      One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection); or assistant_archived when the assistant is archived (restore it first; a number already assigned to it keeps it)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
PUT /api/integrations/whatsapp/connections/{id}/numbers/{numberId}
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
}'
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 Settings

Response attributes
  • dataWhatsAppOperatorAlertsrequired

    8 attributes
    • connection_idstring

    • enabledboolean

    • number_idstring | null

      The account's number that sends the alerts.

    • template_namestring | null

    • template_languagestring | null

    • staff_numbersarray of string

      E.164.

    • updated_atstring | nullISO 8601 timestamp

    • updated_bystring | null

      The 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/connections/{id}/operator-alerts
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/operator-alerts" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Request body

  • enabledbooleanrequired

  • number_idstring | null

  • template_namestring | null

  • template_languagestring | null

  • staff_numbersarray of stringup to 10 items

Returns

200 Saved

Response attributes
  • dataWhatsAppOperatorAlertsrequired

    8 attributes
    • connection_idstring

    • enabledboolean

    • number_idstring | null

      The account's number that sends the alerts.

    • template_namestring | null

    • template_languagestring | null

    • staff_numbersarray of string

      E.164.

    • updated_atstring | nullISO 8601 timestamp

    • updated_bystring | null

      The 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 a message), or invalid_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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
PUT /api/integrations/whatsapp/connections/{id}/operator-alerts
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
}'
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 One result per staff number

Response attributes
  • dataobjectrequired

    1 attribute
    • resultsarray of object

      3 attributes
      • staff_numberstring

      • statusstring

        One of sent failed skipped

      • errorstring | null

        Meta's code, or whatsapp_contact_opted_out when 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), or whatsapp_alert_template_invalid
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/operator-alerts/test
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/operator-alerts/test" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Request body

  • callback_urlstringrequireduriup to 2048 characters

Returns

200 Subscribed

Response attributes
  • dataobjectrequired

    1 attribute
    • subscribedbooleanrequired

      One 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/subscribe
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"
}'
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 The account's numbers

Response attributes
  • dataarray of WhatsAppNumberrequired

    17 attributes
    • idstring

    • connection_idstring

    • phone_number_idstring

    • display_phone_numberstring

    • verified_namestring | null

    • assistant_idstring | null

    • enabledboolean

    • modestring

      One of live test

    • ad_instructionsstring | null

      Instructions for people arriving from an ad.

    • failed_repliesinteger

      List only: replies that could not be sent.

    • failed_turnsinteger

      List only: incoming messages the assistant failed to answer.

    • quality_ratingstring | null

      As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

    • messaging_limit_tierstring | null

      TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

    • statusstring | null

      CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

    • name_statusstring | null

      Display name review: APPROVED, PENDING_REVIEW, DECLINED...

    • health_updated_atstring | nullISO 8601 timestamp

    • next_stepstring

      List only: the one thing to do next for this number, most blocking first.

      One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/sync
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/sync" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 Templates

Response attributes
  • dataarray of WhatsAppTemplaterequired

    13 attributes
    • idstring

    • connection_idstring

    • meta_template_idstring

    • namestring

    • languagestring

    • categorystring

      MARKETING, UTILITY or AUTHENTICATION.

    • statusstring

      As Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...

    • componentsarray of object

      Meta's template components, as given.

    • rejected_reasonstring | null

    • quality_scorestring | null

    • synced_atstringISO 8601 timestamp

    • parametersobject

      How many values each part takes ({{1}} or named placeholders).

      3 attributes
      • headerinteger

      • bodyinteger

      • buttonsarray of integer

    • supportedboolean

      False 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/connections/{id}/templates
curl "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Request body

  • namestringrequired

    Lowercase letters, digits and underscores.

  • languagestringrequired

    Template language code, e.g. en_US or hi.

  • categorystringrequired

    One of UTILITY MARKETING

  • headerstringup to 60 characters

    Text header, at most one placeholder {{1}}.

  • header_examplestringup to 60 characters

    Required when the header has a placeholder.

  • bodystringrequiredup to 1024 characters

    With {{1}} to {{n}} in order, none skipped.

  • body_examplesarray of string

    One non-empty sample value per body placeholder, in order.

  • buttonsarray of objectup to 10 items

    Quick replies and at most 2 URL buttons.

    4 attributes
    • typestringrequired

      One of QUICK_REPLY URL

    • textstringrequiredup to 25 characters

    • urlstringup to 2000 characters

      URL buttons: https, optionally ending in {{1}}.

    • examplestringup to 2000 characters

      Required when the URL ends in {{1}}.

Returns

201 Submitted

Response attributes
  • dataWhatsAppTemplaterequired

    13 attributes
    • idstring

    • connection_idstring

    • meta_template_idstring

    • namestring

    • languagestring

    • categorystring

      MARKETING, UTILITY or AUTHENTICATION.

    • statusstring

      As Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...

    • componentsarray of object

      Meta's template components, as given.

    • rejected_reasonstring | null

    • quality_scorestring | null

    • synced_atstringISO 8601 timestamp

    • parametersobject

      How many values each part takes ({{1}} or named placeholders).

      3 attributes
      • headerinteger

      • bodyinteger

      • buttonsarray of integer

    • supportedboolean

      False 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) or whatsapp_disconnected
  • 422 Meta refused it: meta_<code>
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/templates
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"
}'
Response 201
{
  "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

  • idstringrequired

    WhatsApp connection id.

  • namestringrequired

    Template name.

Returns

200 Deleted

Response attributes
  • dataobjectrequired

    2 attributes
    • namestring

    • deletedinteger

      How 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) or whatsapp_template_not_found
  • 409 whatsapp_disconnected
  • 422 Meta refused it: meta_<code>
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
DELETE /api/integrations/whatsapp/connections/{id}/templates/{name}
curl -X DELETE "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates/NAME" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    WhatsApp connection id.

Returns

200 Templates

Response attributes
  • dataarray of WhatsAppTemplaterequired

    13 attributes
    • idstring

    • connection_idstring

    • meta_template_idstring

    • namestring

    • languagestring

    • categorystring

      MARKETING, UTILITY or AUTHENTICATION.

    • statusstring

      As Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...

    • componentsarray of object

      Meta's template components, as given.

    • rejected_reasonstring | null

    • quality_scorestring | null

    • synced_atstringISO 8601 timestamp

    • parametersobject

      How many values each part takes ({{1}} or named placeholders).

      3 attributes
      • headerinteger

      • bodyinteger

      • buttonsarray of integer

    • supportedboolean

      False 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/{id}/templates/sync
curl -X POST "https://api.brightshoal.com/api/integrations/whatsapp/connections/CONNECTION_ID/templates/sync" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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 returned

    From Meta's Embedded Signup popup.

  • waba_idstringrequired

    From the popup's session info.

  • coexistenceboolean

    Set true for WhatsApp Business app onboarding. Keeps the app's existing registration and skips Cloud API registration, including on retries.

    Default false

  • phone_number_idstring

    The number to register, from the popup's session info. Omitted: registration is skipped.

  • namestringup to 100 characters

    Your label; defaults to WhatsApp <waba_id>.

  • callback_urlstringrequireduriup to 2048 characters

    The 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
  • dataWhatsAppConnectionrequired

    17 attributes
    • idstring

    • org_idstring

    • namestring

    • waba_idstring

      The WhatsApp Business Account id.

    • api_versionstring

    • configuredboolean

      Credentials are stored. False after a disconnect.

    • enabledboolean

      False while paused: messages are not answered.

    • webhook_pathstring

      The path of the callback URL to give Meta (on the API origin).

    • connected_viastring

      One of manual embedded

    • embedded_signupobject | null

      Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.

      7 attributes
      • callback_originstring

      • phone_number_idstring | null

      • coexistenceboolean

        True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections.

      • pendingarray of string

        Not run yet, or failed and to be retried. A step in neither pending nor skipped is done.

      • skippedarray of string

        Registration is skipped when no phone_number_id was given or coexistence is true.

      • failed_stepstring | null

        One of subscribe register sync

      • errorstring | null

        Meta's error code (meta_<code>), never its message.

    • account_statusobject | null

      The latest account_update event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).

      3 attributes
      • eventstring

      • detailobject

      • atstringISO 8601 timestamp

    • review_statusstring | null

      The latest account review decision: APPROVED, REJECTED, PENDING.

    • health_updated_atstring | nullISO 8601 timestamp

    • templates_synced_atstring | nullISO 8601 timestamp

      The last template sync attempt.

    • templates_synced_ok_atstring | nullISO 8601 timestamp

      The last successful template sync.

    • templates_sync_errorstring | null

      Why the last template sync failed; null after a success.

    • numbersarray of WhatsAppNumber

      17 attributes
      • idstring

      • connection_idstring

      • phone_number_idstring

      • display_phone_numberstring

      • verified_namestring | null

      • assistant_idstring | null

      • enabledboolean

      • modestring

        One of live test

      • ad_instructionsstring | null

        Instructions for people arriving from an ad.

      • failed_repliesinteger

        List only: replies that could not be sent.

      • failed_turnsinteger

        List only: incoming messages the assistant failed to answer.

      • quality_ratingstring | null

        As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN.

      • messaging_limit_tierstring | null

        TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED...

      • statusstring | null

        CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED...

      • name_statusstring | null

        Display name review: APPROVED, PENDING_REVIEW, DECLINED...

      • health_updated_atstring | nullISO 8601 timestamp

      • next_stepstring

        List only: the one thing to do next for this number, most blocking first.

        One of resolve_restriction register_number verify_display_name display_name_in_review raise_quality none

  • 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) or whatsapp_already_connected
  • 422 Meta refused the code exchange or the token: {error: meta_<code>, step: exchange | create, message}, the same error codes as the other WhatsApp routes' 422s, with step beside it
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/connections/embedded
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"
}'
Response 201
{
  "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

  • contactIdstringrequired

    WhatsApp contact id.

Request body

  • opted_inbooleanrequired

  • sourcestringrequiredup to 200 characters

    Where the consent came from.

Returns

200 Contact

Response attributes
  • dataWhatsAppContactrequired

    12 attributes
    • idstring

    • number_idstring

    • wa_idstring

      The sender's WhatsApp number.

    • profile_namestring | null

      Sender-set, never verified.

    • first_inbound_atstringISO 8601 timestamp

    • last_inbound_atstringISO 8601 timestamp

    • opted_out_atstring | nullISO 8601 timestamp

      Set by STOP; cleared by START.

    • opted_out_sourcestring | null

    • marketing_opt_in_atstring | nullISO 8601 timestamp

    • marketing_opt_in_sourcestring | null

    • marketing_opt_in_bystring | null

      The user or API key that recorded it.

    • marketing_opt_in_by_namestring | null

      The 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
PUT /api/integrations/whatsapp/contacts/{contactId}/marketing-opt-in
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"
}'
Response 200
{
  "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

  • conversationIdstringrequired

    WhatsApp conversation id.

Returns

200 Contact

Response attributes
  • dataWhatsAppContact | nullrequired

    One of 2 shapes

    WhatsAppContact

    • idstring

    • number_idstring

    • wa_idstring

      The sender's WhatsApp number.

    • profile_namestring | null

      Sender-set, never verified.

    • first_inbound_atstringISO 8601 timestamp

    • last_inbound_atstringISO 8601 timestamp

    • opted_out_atstring | nullISO 8601 timestamp

      Set by STOP; cleared by START.

    • opted_out_sourcestring | null

    • marketing_opt_in_atstring | nullISO 8601 timestamp

    • marketing_opt_in_sourcestring | null

    • marketing_opt_in_bystring | null

      The user or API key that recorded it.

    • marketing_opt_in_by_namestring | null

      The 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/conversations/{conversationId}/contact
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/contact" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • conversationIdstringrequired

    WhatsApp conversation id.

Returns

200 Deliveries

Response attributes
  • dataarray of objectrequired

    5 attributes
    • message_idstring

    • statusstring

      One of failed unknown pending sending sent delivered read

    • errorstring | null

      meta_<code> when failed.

    • updated_atstringISO 8601 timestamp

    • partsinteger

  • 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/conversations/{conversationId}/deliveries
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/deliveries" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • conversationIdstringrequired

    WhatsApp conversation id.

Request body

  • namestringrequiredup to 512 characters

  • languagestringrequiredup to 32 characters

    Template language code, e.g. en_US.

  • parametersobject

    Values for the template's placeholders, in order: as many as the template's parameters counts 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 string

    • bodyarray of string

    • buttonsarray of array of string

      buttons[i] fills the i-th button (only URL buttons take a value).

  • agentobject

    Who is sending, for an API key. A signed-in user is recorded as themselves.

    3 attributes
    • idstring

    • emailstringemail

    • namestring

  • client_message_idstringup to 200 characters

    Set per send; a retry with the same id returns the original instead of sending again.

Returns

201 Queued

Response attributes
  • dataobjectrequired

    6 attributes
    • idstring

      The transcript message id.

    • conversation_idstring

      Where it was added: a new conversation if the old one had ended.

    • rolestring

      One of agent

    • contentstring

      The rendered template text.

    • seqinteger

    • created_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) or whatsapp_template_not_found
  • 409 whatsapp_template_not_approved, whatsapp_contact_opted_out, whatsapp_marketing_opt_in_required, whatsapp_disconnected or client_message_id_reused
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/conversations/{conversationId}/template
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"
}'
Response 201
{
  "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

  • conversationIdstringrequired

    WhatsApp conversation id.

Returns

200 Approved templates

Response attributes
  • dataarray of WhatsAppTemplaterequired

    13 attributes
    • idstring

    • connection_idstring

    • meta_template_idstring

    • namestring

    • languagestring

    • categorystring

      MARKETING, UTILITY or AUTHENTICATION.

    • statusstring

      As Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED...

    • componentsarray of object

      Meta's template components, as given.

    • rejected_reasonstring | null

    • quality_scorestring | null

    • synced_atstringISO 8601 timestamp

    • parametersobject

      How many values each part takes ({{1}} or named placeholders).

      3 attributes
      • headerinteger

      • bodyinteger

      • buttonsarray of integer

    • supportedboolean

      False 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/conversations/{conversationId}/templates
curl "https://api.brightshoal.com/api/integrations/whatsapp/conversations/CONVERSATION_ID/templates" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
  • dataobjectrequired

    4 attributes
    • enabledboolean

    • app_idstring | null

    • config_idstring | null

    • graph_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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/embedded-signup
curl "https://api.brightshoal.com/api/integrations/whatsapp/embedded-signup" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "enabled": true,
    "app_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "config_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "graph_api_version": "string"
  }
}

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

  • numberIdstringrequired

    WhatsApp number id, from the connection's numbers.

Request body

  • namestringrequiredup to 100 characters

  • prefillstring | nullup to 200 characters

    The message WhatsApp opens with.

  • utm_sourcestring | nullup to 100 characters

  • utm_mediumstring | nullup to 100 characters

  • utm_campaignstring | nullup to 100 characters

Returns

201 Created

Response attributes
  • dataWhatsAppLinkrequired

    14 attributes
    • idstring

    • number_idstring

    • namestring

    • codestring

      8 characters starting with C.

    • prefillstring | null

    • utm_sourcestring | null

    • utm_mediumstring | null

    • utm_campaignstring | null

    • urlstringuri

      The wa.me link to share or print as a QR code.

    • created_bystring | null

      The user or API key that created it.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

    • conversationsinteger

      List 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 sync whatsapp_number_already_connected (a number already belongs to another connection)
  • 422 Meta refused the request (meta_<Meta error code>, or meta_http_<status>), or could not be reached (meta_unreachable, which says nothing about whether Meta acted on it)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
POST /api/integrations/whatsapp/numbers/{numberId}/links
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"
}'
Response 201
{
  "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_idstring

    Required for an org-wide key; a project key defaults to its project.

Returns

200 Connected numbers with approved templates

Response attributes
  • dataobjectrequired

    1 attribute
    • dataarray of WhatsAppNumberTemplatesrequired

      6 attributes
      • idstringrequired

      • connection_idstringrequired

      • display_phone_numberstringrequired

      • verified_namestring | nullrequired

      • assistant_idstringrequired

      • templatesarray of objectrequired

        8 attributes
        • idstringrequired

        • namestringrequired

        • languagestringrequired

        • categorystringrequired

        • body_previewstringrequired

          Body text with placeholders intact.

        • variablesobjectrequired

          Placeholder names in parameter order, per component; buttons are indexed by button position.

          3 attributes
          • headerarray of stringrequired

          • bodyarray of stringrequired

          • buttonsarray of array of stringrequired

        • parametersobjectrequired

          3 attributes
          • headerintegerrequired

          • bodyintegerrequired

          • buttonsarray of integerrequired

        • supportedbooleanrequired

  • 400 Project required or conflicts with the project key
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/integrations/whatsapp/numbers/templates
curl "https://api.brightshoal.com/api/integrations/whatsapp/numbers/templates" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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": {}
          }
        ]
      }
    ]
  }
}