WhatsApp API: the first message to a customer with an approved template

Your server can write to a customer in WhatsApp first: an order has shipped, an appointment is tomorrow, a payment has come through. The customer doesn't need to have written to your project before. You send an approved message template and the customer's phone number. Sensever starts the WhatsApp conversation, and the customer's answer arrives in the project's requests like any other message.

WhatsApp lets a business write first only with a template approved by Meta. The same rule applies after the 24-hour window, when a customer wrote a long time ago. How to connect the number and create templates is covered in "WhatsApp in a project: connecting through the Cloud API".

Before you start

• A connected WhatsApp channel. The project has a WhatsApp number with the "Connected" status, and the WhatsApp Business Account ID is filled in the channel settings.

• An approved template. It has the "Approved" status in the "Message templates" block of the channel settings. Templates with text variables {{1}}, {{2}} work, and so do link buttons whose address ends in a variable (https://shop.com/order/{{1}}). Templates with an image, video or document in the header, or with a code-to-copy button, can't be sent yet. You can create a template right in Sensever: channel settings → "Message templates" → "Create template"; Meta reviews it, usually within minutes, and the status changes to "Approved".

• An API key. In "Profile → API" press "Create key", tick the "Project customers" module, keep "Write to customers" and select the project. Such a key writes only to the customers of the selected projects and can't touch your personal chats. The key acts on behalf of the person who issued it, so that person has to be a member of the project team with the rights to create requests and reply in them. How keys work is described in "Sensever API: authorization, content, chats and Flow tasks".

• The project number. Open the project in Sensever: the number is in the page address, https://sensever.com/projects?project=<number>. Or ask for it with the key: GET https://api.sensever.com/v1/chat/customers/projects lists the key's projects with their numbers (see "Project customers API").

• The customer's consent. Meta allows a business to write first only to people who agreed to receive its messages, for example by ticking a box when ordering. Collecting that consent is your responsibility. Meta bills these conversations directly to your Meta account, at its rates for the template's category.

List of approved templates

Get the templates the project can send right now — the same key, a GET request:

curl -s "https://api.sensever.com/v1/chat/projects/PROJECT_NUMBER/whatsapp/templates" \
  -H "Authorization: Bearer $SENSEVER_API_KEY"

{
  "channels": [
    {
      "id": "6b0c1f2e-3d4a-4b5c-9e8f-7a6b5c4d3e2f",
      "name": "Shop",
      "username": "+90 555 000 00 00",
      "templates": [
        {"name": "order_shipped", "language": "en", "category": "UTILITY", "body": "Your order {{1}} has been shipped", "params": 1, "header": null, "footer": null,
         "buttons": [{"index": 0, "type": "url", "text": "View order", "url": "https://shop.com/order/{{1}}", "dynamic": true}], "button_params": 1}
      ]
    }
  ]
}

• Only approved templates that can be sent through the API are listed, for every connected WhatsApp number of the project.

• params — how many variables the template has: send exactly that many values in params.

• name and language go into the send request as they are. If the project has several numbers, pass the number's id as channel_id.

• The list is cached for 5 minutes: a template approved a minute ago may appear a little later.

The request

curl -s -X POST "https://api.sensever.com/v1/chat/projects/PROJECT_NUMBER/whatsapp/messages" \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+90 555 111 22 00",
    "name": "order_shipped",
    "language": "en",
    "params": ["A-7"],
    "customer_name": "Ayse Kaya",
    "client_message_id": "3f8e2a41-6c1d-4b7e-9a52-0d4e8c7b1f60"
  }'

The answer

{
  "thread_id": "14781",
  "channel_id": "090e8209-13bf-4ac9-82f1-2f774e5118ff",
  "new_conversation": true,
  "seq": "1",
  "text": "Order A-7 is on its way."
}

• thread_id is the number of the customer's request in the project.

• new_conversation is true when Sensever started a new conversation with this number, and false when the number already had one. Repeated messages to the same number go to the same conversation.

• text is what the customer reads: the template with its variables filled. The team sees the same text in the request.

• seq is the message number in the request.

The 200 answer means Sensever accepted the message and queued it for WhatsApp. Delivery takes a few seconds. If Meta refuses it (for example, the number has no WhatsApp), the message in the request is marked as undelivered.

What the team sees

A new conversation appears in the project's requests as an in progress request assigned to the person whose key sent the template, with the template in it — the team sees it among the active requests. The customer's answer comes into the same conversation. If the customer already had a conversation, the template is added to it and the request keeps its status.

Errors

Errors come in the common form described in "Sensever API: authorization, content, chats and Flow tasks".

Limits

• Up to 60 messages per minute. Meta adds its own limits for each number: a new number can start a limited number of conversations per day, and the limit grows as customers respond.

• Only templates are sent through this method. A free-text message to a customer who already has a conversation — in WhatsApp within 24 hours of their last message, in Telegram, MAX, Instagram or the website chat — goes through "Project customers API".