Skip to content

Connect WhatsApp

Save Cloud API credentials

Checks the credentials with Meta and, if Meta confirms the phone number belongs to the WhatsApp Business Account, stores them encrypted. This is the manual alternative to the guided Meta signup in the app. Owners and admins only.

PUT/api/v1/channel
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

Headers

  • Cookiestringrequired

    The whatsappx_session cookie the app sets when you sign in. Browsers send it automatically; API keys are not accepted on this endpoint.

    Example
    whatsappx_session=…
  • X-Tenant-IDuuidrequired

    Workspace id. Required for session requests. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • phone_idstringrequired

    Meta phone number id.

    Constraints
    5–30 digits.
    Example
    109876543210987
  • waba_idstringrequired

    WhatsApp Business Account id.

    Constraints
    5–30 digits.
    Example
    102345678901234
  • phonestringoptional

    Phone number to display.

    Example
    +1 555 010 0999
  • tokenstringrequired

    Permanent access token from Meta.

    Constraints
    At least 20 characters.
    Example
    EAAG…
  • secretstringoptional

    Meta app secret, used to verify Meta’s webhook signatures. Required unless whatsappx.si manages the webhook (webhook_managed).

    Constraints
    At least 16 characters.
  • versionstringoptional

    Graph API version.

    Constraints
    Like v23.0.
    Default
    v23.0

Response

200 OKapplication/json

  • configuredboolean

    true when at least one Meta (Cloud API) number is connected.

  • activeenum

    meta when a Cloud API number is connected, otherwise scan.

  • iduuidmay be absent

    Id of the primary Meta channel.

  • providerstringmay be absent

    meta for the primary channel.

  • phone_idstringmay be absent

    Meta phone number id of the primary channel.

  • waba_idstringmay be absent

    WhatsApp Business Account id of the primary channel.

  • phonestringmay be absent

    Phone number of the primary channel.

  • versionstringmay be absent

    Graph API version of the primary channel.

  • webhook_pathstringmay be absent

    Callback path Meta should call, for example /api/webhooks/meta.

  • webhook_urlstringmay be absent

    Full callback URL, when the public URL is configured.

  • webhook_managedboolean

    true when whatsappx.si manages the Meta app and webhook subscription for you.

  • live_sendboolean

    Messages are sent for real (always true).

  • channelsarray<object>may be absent

    All connected Meta numbers.

    Show child attributesHide child attributes5
    • iduuid

      Channel id.

    • phone_idstring

      Meta phone number id.

    • waba_idstring

      WhatsApp Business Account id.

    • phonestring

      Display phone number saved for the channel.

    • versionstring

      Graph API version, for example v23.0.

  • verify_tokenstringmay be absent

    Webhook verify token (verify_ + hex), shown once.

Status codes

  • 200OK. The saved channel configuration. verify_token is included once when a new webhook verify token was generated; enter it in the Meta app’s webhook settings.
  • 400Bad request. Validation or Meta check failed, for example Phone number ID and WABA ID must be 5 to 30 digits, Enter the permanent access token from Meta (at least 20 characters), API version must look like v23.0, Enter the Meta app secret (at least 16 characters), or a message starting with Meta rejected these credentials:. Errors from Meta add meta_code.
  • 502Bad gateway. Meta returned a server error while checking the credentials. Retry later.
  • 401Unauthorized. No signed-in session (unauthorized).
  • 403Forbidden. API keys can never call this endpoint (API keys cannot administer workspaces). A signed-in user who is not an owner or admin gets admin required; a user who is not a member of the workspace gets forbidden.