Project customers API: messages to your customers from your server
Your server can write to a customer of your project: the order is ready, the courier is on the way, the payment came through. Sensever finds the customer's conversation and sends the message where the customer already talks to you: WhatsApp, Telegram, MAX, Instagram or the chat on your website. The team sees the message in the request, sent on behalf of the project.
This works for customers who have already written to the project. To write first to a WhatsApp number that never wrote to you, send an approved template: "WhatsApp API: the first message to a customer with an approved template". Telegram, MAX and Instagram don't let a business write first: the customer has to open the conversation.
The key
In "Profile → API" press "Create key" and tick the "Project customers" module. "Write to customers" is ticked by itself. Select the projects whose customers the key writes to: the list only includes projects where you can write to customers.
Such a key works only with the customers of the selected projects. It can't read or write your personal chats, so a leaked key can't write to people on your behalf. The key acts for the person who issued it: if that person leaves the project team or loses the right to reply in requests, the key stops working there too. How keys work is described in "Sensever API: authorization, content, chats and Flow tasks".
The request
curl -s -X POST "https://api.sensever.com/v1/chat/projects/PROJECT_NUMBER/customers/messages" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+7 999 123-45-67",
"text": "Your order A-7 is ready. You can pick it up today until 20:00.",
"client_message_id": "3f8e2a41-6c1d-4b7e-9a52-0d4e8c7b1f60"
}'The project number is in the page address of the project: https://sensever.com/projects?project=<number>. Your server can also ask for it with the same key:
curl -s "https://api.sensever.com/v1/chat/customers/projects" \
-H "Authorization: Bearer $SENSEVER_API_KEY"{"items": [{"id": "1116", "title": "ULIGHT TR"}]}The list has the projects chosen for the key where you can still reply to customers; id is the project number. A project you left, or where your rights to reply were taken away, drops out of the list, and sending to it returns 403.
Name the customer in one of three ways, exactly one per request:
Field | How Sensever finds the customer |
|---|---|
| The customer's WhatsApp number, or the "Phone" in the request card: typed by your team, or shared by the customer in Telegram or MAX with "Request contact". Spaces, brackets, dashes and |
| The id your website gave the visitor in |
| The request number, for example from an earlier answer of this method |
Other fields:
Field | Required | What it is |
|---|---|---|
| yes | The message, up to 4096 characters |
| no | Where to write when the customer talks to you in several places: |
| no | A UUID of this message. Retry with the same value after a network error, and the customer won't get the message twice |
The answer
{
"thread_id": "14781",
"channel": "max",
"channel_id": "090e8209-13bf-4ac9-82f1-2f774e5118ff",
"seq": "42"
}thread_id— the customer's request in the project.channel— where the message went;channel_id— which connected channel (nullfor the website chat).seq— the message number in the request.
The 200 answer means Sensever accepted the message and queued it. Delivery takes a few seconds. If the messenger refuses it, the message in the request is marked as undelivered, and an operator can retry it.
Errors
Errors come in the common form described in "Sensever API: authorization, content, chats and Flow tasks".
Status |
| What it means |
|---|---|---|
403 |
| The key has no "Project customers" module for this project, or its owner isn't in the project team or can't reply in requests |
404 |
| No conversation with this customer in the project, or not in the |
409 |
| The customer's conversation is in WhatsApp and more than 24 hours passed since their last message. Send an approved template instead |
422 |
| The number has fewer than 5 or more than 20 digits |
422 |
| No customer, two ways to name the customer at once, an empty or too long text; the fields are in |
429 |
| More than 120 messages per minute: wait |
Limits
Up to 120 messages per minute per key.
Text only for now: no files, buttons or templates in this method.
WhatsApp and Instagram accept free text within 24 hours of the customer's last message. In Instagram, Sensever tries once more with the "human agent" tag, which allows up to 7 days when Meta granted it to your app.
Commentaires