Once authentication is in place, you can start integrating Kanal's features directly into your own applications or workflows. The Kanal API is built around REST principles, using standard HTTP requests and returning responses in JSON format.
All API endpoints are available under the following root URL:
https://api.getkanal.com/v1
Use this URL for all your requests. As explained in the authentication guide, only HTTPS is accepted.
The Kanal API communicates exclusively in JSON. For every request you send (especially POST or PATCH methods), include the following headers:
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
The API lets you control the two pillars of Kanal: communication (messages) and the database (contacts).
This is the most common use case. To message a customer outside the 24-hour window, you must use a template previously approved by Meta.
Endpoint: POST /messages
Required data (Body):
The recipient's phone number (international format).
The template name.
The language code (e.g. fr, en).
The personalization variables, if the template contains any.
Example JSON structure for a message with a variable:
{
"to": "33612345678",
"template_name": "order_confirmation",
"language": "en",
"variables": ["John"]
}
You can use the API to sync contacts from an external source into your Kanal database.
Endpoint: POST /contacts
This resource lets you add a new contact or update an existing contact's information. It is the ideal place to manage opt-in status programmatically.
Common fields:
phone: The phone number (unique identifier).
first_name: The first name.
last_name: The last name.
opt_in: A boolean (true/false) to set marketing consent.
The API also lets you add tags to your contacts to trigger automations based on specific conditions.
Endpoint: POST /contacts/tags
This is especially useful for tagging a customer after an action taken in a third-party app, so Kanal can then include them in a dynamic segment or a specific campaign.
To keep the platform stable and comply with Meta's WhatsApp policies, the Kanal API enforces rate limits.
If you exceed the number of requests allowed per minute, the server returns an HTTP 429 error (Too Many Requests). We recommend implementing retry logic with exponential backoff in your code to handle these situations smoothly.
The Kanal API uses standard HTTP status codes to indicate whether a request succeeded or failed:
200 OK: The request succeeded.
201 Created: The resource (contact or message) was created successfully.
400 Bad Request: The request is malformed (missing or invalid parameters).
401 Unauthorized: Authentication problem (missing or invalid API key).
404 Not Found: The requested resource does not exist.
500 Internal Server Error: Something went wrong on our servers.
The API is designed to be predictable and robust. For every error, the JSON response body usually contains an explanatory message to help you identify the cause of the problem.
If you are building a complex integration and have specific questions about an endpoint, feel free to reach out to our technical support through your usual communication channel.