The Outbound SMS Interaction API lets an external system send an SMS to a customer via Talkative. Sending a message through this endpoint creates an interaction and immediately ends it, so there is a logged record that the message was sent. Because the outbound interaction is associated with a queue, if the customer replies, their response is routed back to the correct queue as a normal inbound SMS interaction.
This is useful where an external application (for example a dialler, CRM, or bespoke agent tool) needs to send an SMS through Talkative's SMS service rather than through the console.
Prerequisites
- An SMS number provisioned to your Talkative account.
- A queue with a linked SMS config in the target environment. You will send against this queue's UUID.
- A Core API Bearer token, generated from within Talkative on the API Keys page (Settings → API Keys). See API Authentication.
Endpoint
POST https://{region}.engage.app/api/core/v1/interactions/sms
Authorization: Bearer <bearer token here>
Content-Type: application/json
{
"to": "+447874955000",
"body": "Some body here",
"queue_uuid": "1c545f8c-718d-41a3-b0c1-340a6e2ec8d7"
}Placeholders
The route contains placeholders which must be replaced:
- The region will likely be either eu, euc, us, or au;
- The bearer token must be generated from within Talkative, on the API Keys page.
Request body
Field | Type | Required | Notes |
to | string | Yes | The recipient's mobile number in E.164 format: a leading + followed by 10–15 digits (e.g. +447874955716). The number is also validated against your account, so an unroutable number will be rejected. |
body | string | Yes | The text content of the SMS. Maximum 4096 characters. |
queue_uuid | string | Yes | The UUID of the queue the outbound interaction is associated with. The queue must belong to your company and have a linked SMS messaging config. |
Responses
Status | Meaning |
204 No Content | The SMS was sent successfully. No response body is returned. |
402 Payment Required | The SMS licence limit or the global interaction limit has been reached. No message is sent. |
422 Unprocessable Entity | Validation failed — for example an invalid phone number, a missing or oversized body, or a queue_uuid that does not exist for your company or has no linked SMS config. |
429 Too Many Requests | Rate limit exceeded. The endpoint is limited to 60 requests per minute per company. |
Behaviour
- Calling this endpoint creates and then ends an interaction, leaving a log that the message was sent. The interaction is ended by the system, so if the customer replies it starts a new interaction.
- The outbound interaction is associated with the supplied queue_uuid. When the customer replies, the inbound message is routed to that queue and handled as a normal inbound SMS interaction.
- The sending number is determined by the SMS config linked to the chosen queue.
If you use the same SMS number for both inbound and outbound, customer replies will appear as normal inbound interactions in the Talkative console.
The queue_uuid must belong to a queue that has a linked SMS config in the same environment you are calling. A queue without a linked SMS config will be rejected with a 422. Deleting this config will break any API flow depending on it.
Related
- Outbound & Mass Outbound SMS — sending outbound SMS from within the console, plus Mass Outbound SMS.
- API: Creating Interaction Data — another Core API interaction endpoint, for reference on auth and region placeholders.