Sending Sandbox Messages

WhatsApp, Instagram, and Messenger sandboxes use their provider's regular send endpoint; no separate sandbox-message endpoint is required. Set from to the sandbox keyword or its Application Channel ID. Sandbox accepts only the content types listed below, not every live-channel content object.

Before sending, reach the test-message step in Hub and connect at least one 24-hour session by sending the displayed keyword to the shared sandbox account. Completing setup makes the Sandbox channel available in the application, but is not required for tests on step 3. The API key must belong to the application that owns the sandbox.

{
  "from": "SANDBOX_KEYWORD_OR_APPLICATION_CHANNEL_ID",
  "to": "SESSION_EXTERNAL_IDENTIFIER",
  "content": {
    "text": "Hello from the sandbox!"
  }
}

Use the endpoint for the configured provider:

Provider	Endpoint
WhatsApp	POST /v1/communication/whatsapp/message
Instagram	POST /v1/communication/instagram/message
Messenger	POST /v1/communication/messenger/message

from accepts only the sandbox keyword shown in Hub or that sandbox's Application Channel ID. It does not accept the shared WhatsApp number, Instagram username, or Messenger page name. to is the external identifier returned for a connected sandbox session.

Supported Sandbox content

Send exactly one supported content key per request:

Provider	Supported content keys
WhatsApp	text, fake Sandbox template, imageUrl, videoUrl, documentUrl
Instagram	text, imageUrl, videoUrl
Messenger	text, imageUrl, videoUrl

Sandbox does not support live-channel-only features such as typing, reactions, interactive messages, or Messenger templates. Unsupported content returns UNSUPPORTED_MESSAGE_TYPE.

Authentication and webhook configuration

The Hub screen sends with the signed-in organization; the public API uses the owning application's x-api-key. In both cases the sandbox session must be connected and unexpired. An API key cannot send through a sandbox from another application.

Configure and read subscriptions from the moment a Sandbox is created, including while it is pending, with the standard channel endpoints:

POST /v1/communication/channel/{applicationChannelId}/webhook/{webhookId}/configure
GET  /v1/communication/channel/{applicationChannelId}/webhook/{webhookId}/config

Use the Sandbox Application Channel ID as {applicationChannelId}. Send {"events": []} to unsubscribe. The response identifies the target as applicationChannelId.

API key examples

curl -X POST https://app.chatt2.me/v1/communication/messenger/message \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'content-type: application/json' \
  --data '{"from":"YOUR_SANDBOX_KEYWORD","to":"SESSION_EXTERNAL_IDENTIFIER","content":{"text":"Hello from the sandbox!"}}'

curl -X POST 'https://app.chatt2.me/v1/communication/channel/YOUR_SANDBOX_APPLICATION_CHANNEL_ID/webhook/YOUR_WEBHOOK_ID/configure' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'content-type: application/json' \
  --data '{"events":["messages"],"enabled":true}'

WhatsApp template example

List the Sandbox catalog with GET /v1/communication/channel/whatsapp/templates/{applicationChannelId}. It is localized and read-only, returns phoneNumber: null, and marks examples with sandboxFamily. Templates use the regular WhatsApp template body. The following image template supplies both the body variable and image URL:

{
  "from": "SANDBOX_KEYWORD_OR_APPLICATION_CHANNEL_ID",
  "to": "SESSION_EXTERNAL_IDENTIFIER",
  "content": {
    "template": {
      "id": "10000000-0000-4000-8000-000000000003",
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": { "link": "https://example.com/image.jpg" }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "variable": "1",
              "text": "Dani"
            }
          ]
        }
      ]
    }
  }
}

Incoming webhook identity

Sandbox message events include message.is_sandbox: true. The recipient uses the owning keyword as recipient.id and includes the sandbox Application Channel ID:

{
  "eventType": "message",
  "payload": {
    "provider": "whatsapp",
    "direction": "IN",
    "message": {
      "id": "a16c0971-1887-4612-a0b2-d9489d6ca04f",
      "type": "Text",
      "content": { "text": "Hello" },
      "is_sandbox": true
    },
    "sender": {
      "id": "5511993986082",
      "username": "5511993986082"
    },
    "recipient": {
      "id": "YOUR_SANDBOX_KEYWORD",
      "applicationChannelId": "e690cc45-4abe-4f83-8373-01e7026797ad"
    }
  }
}

Sandbox limits are shared by the organization across configured sandboxes. Disconnecting or deleting the owning application clears sessions, webhook configuration, and the keyword, but does not reset usage.