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
- Give the channel a name your team sees in the inbox, for example Mobile app chat.
- Optional: the replies webhook, a public
https://address. - 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,phoneandemailfill the contact.message.text, ormessage.type(image,video,audio,document,location) with a public httpsurl.message.idavoids duplicates if you retry;message.replyToquotes 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-Signatureheader: 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 answer | Why | What to do |
|---|---|---|
| 401 / 403 | Wrong or missing secret or signature | Copy the secret again; sign the raw body |
| 200 but nothing in the inbox | No sender.id, or neither text nor url | Check the JSON shape above |
| Replies fail with “no reply address” | No replies webhook set | Add it in the channel’s settings |
| Replies fail with HTTP 4xx | Your webhook refused them | Check your endpoint’s logs and signature check |