Connect a channel

A channel connection links one messaging account, such as a WhatsApp Business number or a Telegram bot, to your organization. Until one exists, no messages arrive and none can be sent.

Connecting takes four steps. The fourth is the one people forget:

1. Pick a platform.
2. Collect the platform's credentials.
3. Call POST /channels/connect. engage-ai checks the credentials, stores them encrypted, and returns a webhook URL.
4. Register that webhook URL with the platform. Until you do, the connection exists but no message will ever arrive.

Supported platforms

Ask the API rather than hard-coding a list. New platforms appear here without any change on your side.

curl https://api.getengageai.app/channels/providers -H "Authorization: Bearer $ENGAGE_API_KEY"

Each entry describes what the platform can do:

{
  "providerKey": "whatsapp_cloud",
  "displayName": "WhatsApp Business",
  "capabilities": {
    "text": true, "media": true, "templates": true,
    "maxTextLength": 4096,
    "replyWindowHours": 24
  },
  "configSchema": { "type": "object", "properties": { "businessAccountId": {}, "defaultTemplateName": {} } },
  "rateLimitPerMinute": 600,
  "docsUrl": "https://developers.facebook.com/docs/whatsapp/cloud-api"
}

• capabilities.replyWindowHours is how long after the customer's last message you may send a free-form reply. WhatsApp's is 24; Telegram's is null, meaning no window.
• configSchema is a JSON Schema for the optional settings object. It does not describe credentials; those are listed per platform below.

Telegram

1. Create the bot

In Telegram, message @BotFather (the one with the blue tick):

/newbot
→ name:     Acme Support
→ username: acme_support_bot      (must end in "bot")
← 7654321:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

The reply is your bot token. The digits before the colon, 7654321, are the bot id.

2. Choose a secret token

Make up a random string. Telegram sends it back with every message, and engage-ai checks it, which proves the request really came from Telegram. Generate one rather than typing something memorable:

openssl rand -hex 24

3. Connect

curl -X POST https://api.getengageai.app/channels/connect \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerKey": "telegram_bot",
    "externalAccountId": "7654321",
    "displayName": "Acme Support (Telegram)",
    "credentials": {
      "botToken": "7654321:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw",
      "webhookSecretToken": "<your secret token>"
    },
    "settings": { "botUsername": "acme_support_bot" }
  }'

The credential is named webhookSecretToken, not secretToken. A misspelled key is dropped without an error: the connection is created, and then every inbound message fails its check with 401.

4. Register the webhook

curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -d "url=<webhookUrl from the response>" \
  -d "secret_token=<your secret token>"

{"ok":true,"result":true,"description":"Webhook was set"} means it worked. Now message your bot. A conversation appears in GET /conversations within a second or two.

If nothing arrives, https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo shows last_error_message, which usually says exactly what is wrong.

WhatsApp Business

WhatsApp uses Meta's Cloud API. You need a Meta Business account, a Meta developer app with WhatsApp added, and a phone number. Meta gives you a free test number straight away, which can message up to five recipients you list yourself. Use it first; move your real number over once everything works.

1. Collect four values

Double-check the phone number ID. The WhatsApp Business Account ID sits on the same screen and is the usual mix-up. If the wrong ID is saved, inbound messages cannot be matched to your connection and are dropped, and nothing reports an error.

2. Connect

curl -X POST https://api.getengageai.app/channels/connect \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerKey": "whatsapp_cloud",
    "externalAccountId": "102290129340398",
    "displayName": "Acme Support (WhatsApp)",
    "credentials": {
      "accessToken": "EAAG…",
      "appSecret": "…",
      "verifyToken": "<a string you chose>"
    },
    "settings": { "businessAccountId": "…" }
  }'

settings is optional. defaultTemplateName names the approved template used to re-engage a customer outside the 24-hour window.

3. Register the webhook in Meta

1. Meta App Dashboard → WhatsApp → Configuration → Edit the callback.
2. Callback URL: paste webhookUrl exactly, including the ?connection= query string.
3. Verify token: the same string you sent as verifyToken.
4. Press Verify and save. Meta sends a GET with a challenge; engage-ai answers it only if the verify token matches.
5. Subscribe to the messages field, or nothing is delivered.

Then send a WhatsApp message to the number to confirm it works.

Going live

These are Meta's rules, not engage-ai's, but you will meet them in production:

• The test number reaches only five hand-listed recipients.
• Meta requires business verification before a number can message beyond its starting tier.
• Messaging limits start low, typically 250 unique customers in 24 hours, and rise with good quality.
• Outside the 24-hour window only approved templates send. A free-form reply after that fails with REPLY_WINDOW_CLOSED.

The connect response

{
  "connectionId": "1bf4b04d-…",
  "webhookUrl": "https://api.getengageai.app/webhooks/telegram_bot?connection=7654321",
  "webhookSecret": null,
  "registration": {
    "verifyWith": "webhookSecretToken",
    "instructions": "…"
  },
  "verified": true,
  "verification": null
}

What verification proves

Credentials are checked with the platform before they are stored. There are three outcomes:

verified: true does not mean messages will arrive. WhatsApp's check proves the access token and phone number ID; the app secret and verify token are only used once Meta calls the webhook. Telegram's check proves the bot token; the secret token is only used on delivery. The first inbound message is the real confirmation.

Managing connections

# List connections with their status and reply mode
curl https://api.getengageai.app/channels/connections -H "Authorization: Bearer $ENGAGE_API_KEY"

# Disconnect one
curl -X DELETE https://api.getengageai.app/channels/connections/$CONNECTION_ID \
  -H "Authorization: Bearer $ENGAGE_API_KEY"

status is one of PENDING, ACTIVE, DEGRADED, REVOKED (the platform rejected the credentials, so someone must reconnect), DISABLED or ERROR.

Reconnecting. Call POST /channels/connect again with the same providerKey and externalAccountId. It updates the connection in place: same connectionId, new credentials, checked again. This is how you replace an expired token. If the response has a new webhookSecret, update the registration at the platform.

Disconnecting destroys the stored credentials and stops accepting messages for that account. Conversations and messages are kept. The account is released, so it can be connected again later, by you or by another organization.

One account, one organization. Connecting an account that another organization is actively using returns 409 CONFLICT. Inbound messages carry no tenant marker, so one number cannot serve two organizations.

Errors