Centre d’aide / Canal personnalisé (API)

Canal personnalisé (API)

Reliez n’importe quelle autre application ou système à la boîte de réception PALMS en HTTP.

Utilisez un canal personnalisé pour tout ce que PALMS ne connecte pas directement : la messagerie de votre application mobile, un système de réservation, une place de marché, un outil interne. Votre système envoie les messages par une requête HTTP, et PALMS envoie les réponses de votre équipe au webhook de votre système. Environ 10 minutes pour un développeur.

Avant de commencer

  • Un développeur, ou un outil qui envoie et reçoit des requêtes HTTP (Zapier, Make, n8n…).
  • Facultatif : une adresse https où votre système reçoit les réponses — voir recevoir les réponses.

Créer le canal

  1. Donnez au canal un nom visible dans la boîte de réception, par exemple Messagerie de l’application.
  2. Facultatif : le webhook des réponses, une adresse publique https://.
  3. Cliquez sur Créer le canal. PALMS crée l’adresse privée du canal et un secret de signature (affiché à la demande ; gardez-le secret).

Envoyer des messages

Envoyez en POST du JSON à l’adresse du canal, avec le secret comme jeton « Bearer » :

curl -X POST 'https://…/v1/webhooks/custom/api_…' \
  -H 'Authorization: Bearer <secret de signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender": { "id": "client-42", "name": "Ama Mensah", "phone": "+233201234567" },
    "message": { "id": "msg-1001", "text": "Bonjour ! J’ai besoin d’aide pour ma commande." }
  }'
  • sender.id (obligatoire) est l’identifiant de la personne dans votre système. name, phone et email remplissent le contact.
  • message.text, ou message.type (image, video, audio, document, location) avec une url publique en https.
  • message.id évite les doublons si vous renvoyez ; message.replyTo cite un message précédent.
  • Jusqu’à 50 messages à la fois dans messages: [ … ].
  • Au lieu du jeton Bearer, vous pouvez signer le corps : X-Palms-Signature: sha256=<HMAC-SHA256 du corps brut, en hexadécimal>.

Recevoir les réponses

Quand votre équipe répond, PALMS envoie en POST ce JSON à votre webhook :

{
  "event": "message", "id": "…", "channelId": "…", "timestamp": "2025-01-01T10:00:00.000Z",
  "recipient": { "id": "client-42", "phone": "+233201234567", "email": null },
  "message": { "type": "text", "text": "Bonjour Ama, …", "url": null, "filename": null, "replyTo": "msg-1001" }
}
  • Vérifiez l’en-tête X-Palms-Signature : le HMAC-SHA256 du corps brut avec le secret de signature.
  • Répondez en HTTP 2xx sous 15 secondes. En cas de 429 ou 5xx, PALMS réessaie. Vous pouvez renvoyer {"id": "…"} avec votre identifiant de message.
  • L’adresse doit être publique en https (pas d’adresse locale ou de réseau privé).

Tester la connexion

Envoyez avec la requête ci-dessus un message dont le texte est le code affiché dans l’assistant (par exemple PALMS-4821). L’étape affiche une coche ; si vous avez indiqué un webhook, PALMS y envoie sa réponse.

Dépannage

Réponse HTTPPourquoiQue faire
401 / 403Secret ou signature absent ou fauxRecopiez le secret ; signez le corps brut
200 mais rien dans la boîtePas de sender.id, ou ni text ni urlVérifiez la forme du JSON ci-dessus
Réponses en échec « pas d’adresse de réponse »Aucun webhook des réponsesAjoutez-le dans les réglages du canal
Réponses en échec HTTP 4xxVotre webhook les a refuséesVérifiez les journaux de votre serveur et la vérification de signature

Toujours bloqué ?

Notre équipe répond sur WhatsApp, en français ou en anglais.

WhatsAppOuvrir Graphwafe