Skip to content

Send WhatsApp from your systems

One call sends one approved WhatsApp template to one person. Kontakt finds or creates the person, applies the same rules as a journey message, bills it like one, and shows it in the inbox.

Use this when the decision to message someone is made outside Kontakt: your backend after a failed payment, or a Customer.io, Braze, or MoEngage journey that should send its WhatsApp step through Kontakt. When Kontakt should decide what happens next, send an event instead and build a journey.

Before you start

Send a template

curl https://api.usekontakt.com/v1/messages/whatsapp \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-failed-8841" \
  -d '{
    "user_id": "usr_123",
    "phone": "08031234567",
    "template": "payment_failed",
    "variables": ["Ada", "N5,000"]
  }'
FieldNotes
user_id, email, phone, customer_idAt least one. The person is found or created the same way as POST /v1/events. Set "upsert_customer": false to only message people who already exist.
traitsOptional profile updates, as on POST /v1/events.
template or template_idThe template name as shown in Kontakt or as approved by WhatsApp, or its ID.
languageOptional. Picks the language when the same name exists in several, for example en_GB.
variablesBody variables in order, ["Ada", "N5,000"], or by position, {"1": "Ada"}. Every body variable is required.
fromOptional. The WhatsApp number to send from, as a phone number or connection ID. Defaults to the person's open conversation, then your newest number.
when_human_liveskip or send. What to do when a teammate is in a live chat with the person. Defaults to skip for Marketing templates and send for Utility and Authentication.
idempotency_keyOptional. Also read from the Idempotency-Key or X-CIO-Idempotency-Key header.

What comes back

StatusMeaning
201Sent to WhatsApp. message_id is the Kontakt message, provider_message_id the WhatsApp ID, conversation_id the inbox conversation.
200This idempotency key was already sent. The first result comes back with deduplicated: true. Nothing is sent again.
202Not sent, with a reason. See below.
402Not enough credits.
409A request with the same idempotency key is still being sent, or the identity fields match two different people.
422Unknown or unapproved template, missing variables, unknown from number, or WhatsApp rejected the message (PROVIDER_ERROR).
502WhatsApp could not be reached. Retry with the same idempotency key.

A 202 carries one of these reasons:

ReasonWhy
opted_outThe person opted out of WhatsApp marketing. Marketing templates only.
frequency_capThe person reached the marketing cap. Applies when WhatsApp is switched on in the contact policy.
holdoutThe person is in a holdout group.
quiet_hoursIt's quiet hours for the person. resume_at says when they end. Kontakt does not queue the message, so send again after that time.
human_liveA teammate is chatting with the person: the conversation is open and a teammate took it over or replied in the last 24 hours.
no_phoneThe person has no phone number.

A skipped or failed send can be retried with the same idempotency key. Only a sent message is deduplicated.

How it behaves

  • Same rules as journeys. Marketing templates follow opt-outs, and the caps and quiet hours when WhatsApp is switched on in the contact policy. Utility and Authentication templates are treated as transactional and are not held back by them. If the person messaged you in the last 24 hours, caps and quiet hours don't apply.
  • Billing. The message is charged like any other WhatsApp template from Kontakt, at the rate for the template's category and the person's country. See Channel pricing.
  • Inbox. The message appears in the person's conversation, and a new conversation is opened if they have none. Replies land in the inbox and record a whatsapp.replied event that journeys can use. With Customer.io connected, the reply and delivery status are also sent to Customer.io.
  • Counts as a touch. A sent Marketing template counts towards the caps and towards order attribution like a journey message.
  • Tracked buttons. A link button with Track clicks turned on in the template is filled with a short link for each person, so you don't send a value for it. Links in variables are sent as you wrote them. See Tracked links.

From Customer.io

In a Customer.io journey, add a Send and receive data (webhook) action:

Set the request

Method POST, URL https://api.usekontakt.com/v1/messages/whatsapp. Add the headers Authorization: Bearer pk_live_your_key and Content-Type: application/json.

Write the body

{
  "user_id": "{{customer.id}}",
  "phone": "{{customer.phone}}",
  "template": "kyc_reminder",
  "variables": ["{{customer.first_name}}"]
}

Leave retries on

Customer.io sends an X-CIO-Idempotency-Key header with each webhook, so a retried call never sends the message twice.