Skip to main content
Use this when your system needs to write to a contact: a payment reminder, a status update, an answer your backend produced. You always call the same endpoint, Session Start. Despite the name, it doesn’t always start something new:
  • The contact has an open conversation on that channel connection: the message goes into that conversation, and the history stays together.
  • There is no open conversation: Talqui opens one and sends the message as the first one. See New conversation.
You don’t need to know which case applies. Talqui decides it on every call.
1

Get an access token

Create an API credential in Settings → API credentials and exchange it for a token. Do this on your server: the secret must never reach a browser or app.
The token lasts 1 hour. Reuse it until then.
2

Send the message

Point to the contact and to the channel connection that talks to them. Use contactID if you already have the Talqui contact ID, or contactExternalID (a phone number, for example) to let Talqui find the contact.
The response carries the contact, the session and the message. When the message went into an open conversation, session.sessionID is the ID that conversation already had.

What happens to an open conversation

The message joins the conversation without changing how it is being handled:
  • It stays in the same inbox, with the same operator or automation. sessionType and sessionKind only apply when a conversation is created.
  • The one exception is sessionType: "manual" with an operatorID: the conversation is handed to that operator.

WhatsApp rules

On WhatsApp (official API), Talqui protects the number from being flagged as spam:
  • The contact must have answered. If the open conversation only has messages sent by you, a new message is refused with 412 BLOCKED_BY_ABSENCE_OF_RESPONSE. Wait for the contact to reply. Approved models of the Utility category are not subject to this rule.
  • The same model goes out at most 3 times per conversation. The fourth attempt returns 409 BLOCKED_BY_REPEATED_CAMPAIGN_MODEL_ID.
  • Outside the 24-hour window, WhatsApp only accepts an approved model: send its campaignModelID, as in New conversation.

Errors worth handling

To send the same message to many contacts at once, use Campaigns instead.

Next steps

Session Start

Every field, file and audio messages, and the rules of each channel.

Manage the conversation

Assign it to an operator, transfer it to an inbox or close it through the API.