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
`phone`	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 `+` are ignored
`customer_id`	The id your website gave the visitor in `SenseverWidget.identify()`, only when the call was signed with `user_hash` ("Sensever widget: installation and setup"). An unsigned id is what the visitor's browser claimed, so it isn't used
`thread_id`	The request number, for example from an earlier answer of this method

Other fields:

Field	Required	What it is
`text`	yes	The message, up to 4096 characters
`channel`	no	Where to write when the customer talks to you in several places: `whatsapp`, `telegram`, `max`, `instagram` or `web` (the website chat). Without it, Sensever takes the conversation where the customer wrote last
`client_message_id`	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 (null for 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	`error.code`	What it means
403	`forbidden`	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	`customer_not_found`	No conversation with this customer in the project, or not in the `channel` you named, or its channel is disconnected
409	`whatsapp_window_closed`	The customer's conversation is in WhatsApp and more than 24 hours passed since their last message. Send an approved template instead
422	`phone_invalid`	The number has fewer than 5 or more than 20 digits
422	`validation_failed`	No customer, two ways to name the customer at once, an empty or too long text; the fields are in `error.details.fields`
429	`rate_limited`	More than 120 messages per minute: wait `Retry-After` seconds

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.

Project customers API: messages to your customers from your server

Project customers API: messages to your customers from your server

The key

The request

The answer

Errors

Limits

এরপর পড়ুন

এই বিভাগে পরবর্তী

একই রকম

মন্তব্য

লেখকগণ