Help Centre / Custom channel (API)

Custom channel (API)

Connect any other app or system to the PALMS inbox over HTTP.

Use a custom channel for anything PALMS doesn’t connect directly: your mobile app’s chat, a booking system, a marketplace, an internal tool. Your system sends messages in with an HTTP request, and PALMS posts your team’s replies to your system’s webhook. About 10 minutes for a developer.

Before you start

  • A developer, or a tool that sends and receives HTTP requests (Zapier, Make, n8n…).
  • Optional: an https address where your system receives replies — see receive replies.

Create the channel

  1. Give the channel a name your team sees in the inbox, for example Mobile app chat.
  2. Optional: the replies webhook, a public https:// address.
  3. Click Create the channel. PALMS creates the channel’s private address and a signing secret (shown on demand; keep it secret).

Send messages in

POST JSON to the channel’s address, with the secret as a bearer token:

curl -X POST 'https://…/v1/webhooks/custom/api_…' \
  -H 'Authorization: Bearer <signing secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender": { "id": "customer-42", "name": "Ama Mensah", "phone": "+233201234567" },
    "message": { "id": "msg-1001", "text": "Hello! I need help with my order." }
  }'
  • sender.id (required) is your system’s id for the person. name, phone and email fill the contact.
  • message.text, or message.type (image, video, audio, document, location) with a public https url.
  • message.id avoids duplicates if you retry; message.replyTo quotes an earlier message.
  • Send up to 50 at once in messages: [ … ].
  • Instead of the bearer token you can sign the body: X-Palms-Signature: sha256=<HMAC-SHA256 of the raw body, hex>.

Receive replies

When your team answers, PALMS POSTs JSON to your replies webhook:

{
  "event": "message", "id": "…", "channelId": "…", "timestamp": "2025-01-01T10:00:00.000Z",
  "recipient": { "id": "customer-42", "phone": "+233201234567", "email": null },
  "message": { "type": "text", "text": "Hi Ama, …", "url": null, "filename": null, "replyTo": "msg-1001" }
}
  • Check the X-Palms-Signature header: the HMAC-SHA256 of the raw body with the signing secret.
  • Answer with HTTP 2xx within 15 seconds. On 429 or 5xx, PALMS retries. You may return {"id": "…"} with your own message id.
  • The address must be public https (no local or private network addresses).

Test your connection

Send a message whose text is the code shown in the wizard (for example PALMS-4821) with the request above. The step shows a tick; if you set a replies webhook, PALMS posts its answer there.

Troubleshooting

HTTP answerWhyWhat to do
401 / 403Wrong or missing secret or signatureCopy the secret again; sign the raw body
200 but nothing in the inboxNo sender.id, or neither text nor urlCheck the JSON shape above
Replies fail with “no reply address”No replies webhook setAdd it in the channel’s settings
Replies fail with HTTP 4xxYour webhook refused themCheck your endpoint’s logs and signature check

Still stuck?

Our team answers on WhatsApp, in English or French.

WhatsAppOpen Graphwafe