Kanal APIMessaging API
Trigger an automation
Start an automation flow for a contact via an incoming webhook.
POST /api/v1/automations/{webhook_id}Starts an automation that has an Incoming Webhook trigger node.
{webhook_id} is the UUID of that trigger node (found in the automation
editor). The automation must be active and belong to the API key's
WhatsApp number.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
phone_number | string | required | Contact phone. Non-digits stripped; validated as a possible number. |
variables | object | optional | Arbitrary key→value map injected into the automation session variables. |
shopify_customer_id | string/number | optional | Must be numeric; links the contact to a Shopify customer. |
Request
curl -X POST https://api.getkanal.com/api/v1/automations/3f9c1a2b-4d5e-6789-abcd-ef0123456789 \
-H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+33612345678",
"variables": { "discount_code": "WELCOME10" },
"shopify_customer_id": "8472635"
}'Response 200 OK
{ "message": "Incoming webhook triggered" }If the contact is blocked by the automation's re-entry rule, you still get
200 with { "message": "Contact blocked by re-entry rule" } (no flow runs).
Errors
| Status | Body | Cause |
|---|---|---|
401 | { "message": "Invalid API key" } | Key doesn't own this automation's number. |
404 | { "message": "Incoming webhook not found" } / { "message": "Automation not found" } | Unknown webhook_id. |
400 | { "message": "Automation is not active" } | Automation disabled. |
400 | { "message": "phone_number is required" } / { "message": "Invalid phone_number format" } | Bad contact. |
400 | { "message": "shopify_customer_id must be numeric" } | Non-numeric Shopify id. |
This endpoint uses a { "message": "..." } error shape (not { "error" }).