> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a message

> Send a message to a contact from your own system. Talqui delivers it in the open conversation, or opens one when there is none.

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](https://docs.talqui.chat/guides/platform/sessions/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](https://docs.talqui.chat/guides/basics/new-conversation.md).

You don't need to know which case applies. Talqui decides it on every call.

**1. Get an access token**

Create an [API credential](https://docs.talqui.chat/guides/introduction/authentication/api-credentials.md) in **Settings → API credentials** and exchange it for a token. Do this on your server: the secret must never reach a browser or app.

```bash theme={null}
curl -X POST https://id-api.talqui.chat/api/auth/oauth2/token \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d grant_type=client_credentials \
  -d scope=urn:talqui::::permission/all
```

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.

```bash theme={null}
curl -X POST https://api.talqui.chat/tenants/<TENANT_ID>/sessions \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "<CHANNEL_URN>",
    "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
    "contactExternalID": "5511999990000",
    "messageKey": "text",
    "messageValue": "Hi Maria, your payment was confirmed."
  }'
```

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](https://docs.talqui.chat/guides/basics/new-conversation.md).

## Errors worth handling

| Status | Error | What to do |
| - | - | - |
| `409` | `SESSION_DISPATCH_IN_PROGRESS` | Another message to the same contact is still being sent. Send them one at a time, waiting for each answer. |
| `412` | `BLOCKED_BY_ABSENCE_OF_RESPONSE` | WhatsApp: wait for the contact to reply, or use a Utility model. |
| `409` | `BLOCKED_BY_REPEATED_CAMPAIGN_MODEL_ID` | WhatsApp: this model already went out 3 times in the conversation. |
| `429` | `SESSION_START_RATE_LIMITED` | Too many calls in a short period. Wait a bit and retry. |

> [!NOTE]
>
> To send the same message to many contacts at once, use [Campaigns](https://docs.talqui.chat/guides/platform/campaigns) instead.

## Next steps

> [card] [Session Start](https://docs.talqui.chat/guides/platform/sessions/session-start)
>
> Every field, file and audio messages, and the rules of each channel.

> [card] [Manage the conversation](https://docs.talqui.chat/guides/platform/sessions/session-management.md)
>
> Assign it to an operator, transfer it to an inbox or close it through the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.