Send WhatsApp Messages with the API

Send WhatsApp Messages with the API

Check WhatsApp readiness, choose a business number and send a message or an approved template through the Zonitel API.

Use the Zonitel API to check WhatsApp availability, choose a business number, and send free-text messages or approved templates from your own software. Zonitel resolves the conversation thread automatically.

Before you start

Connect WhatsApp in Zonitel Office first using Connect WhatsApp Business. Onboarding cannot be completed through the API. Your account needs active WhatsApp access and a usable business number.

Create a Zonitel credential through Private Integrations. Every request below uses Authorization: Bearer YOUR_TOKEN and X-Client-Id: YOUR_CLIENT_ID. Keep both values on your server.

Replace all uppercase placeholders before running an example. YOUR_WHATSAPP_NUMBER and RECIPIENT_NUMBER must be full international numbers in E.164 format, including the country code. Use a recipient who has agreed to receive your messages.

1. Check whether the account can send

curl --request GET \
  --url https://api.zonitel.com/api/v3/integrations/whatsapp/status \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'Accept: application/json'

Read canSend first. A response with HTTP 200 and canSend: false is a normal availability result. Read reason and message to understand what is missing. The response also includes onboarded, subscribed, accessUntil and usableNumbers.

Resolve the reported issue in Office before attempting a send. In WhatsApp settings, use Business config for the connected business, Subscription for access, and Numbers & templates for numbers and approved messages.

2. Choose the sender and message type

Using the same authentication headers, request GET https://api.zonitel.com/api/v3/integrations/whatsapp/numbers. Use the returned number as from; you do not need to supply Meta’s internal phone-number ID. The result also shows verifiedName, isDefault and receivesReplies.

• An open 24-hour conversation window: you can send free text.
• A closed window: use an approved template to contact the recipient.

To choose a template, request GET https://api.zonitel.com/api/v3/integrations/whatsapp/templates. Review its name, language, body and paramsCount. This endpoint lists approved templates. Match the number and order of replacement values to the template’s placeholders.

3. Send the message

For free text while the conversation window is open:

curl --request POST \
  --url https://api.zonitel.com/api/v3/integrations/whatsapp/send \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{"from":"YOUR_WHATSAPP_NUMBER","to":"RECIPIENT_NUMBER","text":"Your appointment is confirmed."}'

For an approved template, replace APPROVED_TEMPLATE_NAME with a name returned for your account. This example assumes that template has exactly two body placeholders:

curl --request POST \
  --url https://api.zonitel.com/api/v3/integrations/whatsapp/send \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{"from":"YOUR_WHATSAPP_NUMBER","to":"RECIPIENT_NUMBER","template":{"name":"APPROVED_TEMPLATE_NAME","params":["CUSTOMER_NAME","APPOINTMENT_TIME"]}}'

The send schema also supports medias and template buttonParams. Use the API reference for their structure and the parameters your approved template requires.

Read the result before retrying

A successful response includes id, conversationId, type, status, direction, from and to. Save the message and conversation identifiers with your own record. sent confirms the send result; it is not proof of delivery or reading.

• 400: check required fields, the sender number, template approval and placeholder count.
• 401: review the Zonitel token and client identifier.
• 403: check the availability endpoint and resolve the missing WhatsApp access or connection in Office.
• 502: read the error message. If the conversation window is closed, send an approved template instead of repeating free text. Other temporary failures may require a later retry.

If a request times out, check the conversation before resending to avoid duplicate messages. Start with one permitted test recipient before automating customer messages.