Generate Message
Send a message flow's opening message to a recipient and start (or continue) a conversation with them.
The message sent is always the message flow's initiationMessage. It is recorded as an outbound message on the conversation between the flow and the recipient. If a conversation with that recipient already exists for the flow, the message is added to it.
What actually gets delivered depends on the flow's messageChannel:
Twilio-SMSandTelnyx-SMS: the SMS is sent immediately, from the phone number bound to the flow's agent.autopilothas no effect and no flow delay is applied.Twilio-Email: known issue. The message is recorded on the conversation, but no email is sent yet.- Any other channel (WhatsApp, Facebook): not supported by this endpoint.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
flowIdstringrequiredThe _id of the message flow sending the message. The flow must be in this workspace and active (isActive: true).
tostringrequiredThe recipient. For SMS flows use E.164 format (for example +14155550123). The recipient must be in the same country as the flow's sending number.
metadataobjectautopilotbooleandefault: falseAccepted but has no effect today: SMS is always sent immediately, and email is not sent.
dynamicobjectAccepted but not used.
Requirements
- The flow must have an agent, and that agent must have a phone number bound to it (for SMS flows).
- The workspace needs a wallet balance of at least 1 to send an SMS.
Response Fields
statusstringsuccess.
conversation_idstringThe _id of the new or existing conversation.
message_idstringThe _id of the new message within the conversation.
messagestringThe text sent. Always the message flow's initiationMessage.
channelstringThe flow's messageChannel, for example Twilio-SMS.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Workspace ID is required"} | No x-workspace-id |
400 | {"error": "flowId and 'to' are required!"} | flowId or to missing |
400 | {"error": "Invalid configuration", "details": "No active message flow found in workspace."} | The flow isn't in this workspace, or isn't active |
400 | {"error": "OmniFlowAgent not found"} | The flow has no agent |
400 | {"error": "'to' must be a valid phone number for SMS pathways"} | to isn't a phone number (SMS flows) |
400 | {"error": "Phone number associated with the message flow not found."} | No phone number is bound to the flow's agent |
400 | {"error": "Country code mismatch: ..."} | Sender and recipient are in different countries |
403 | {"error": "..."} | The workspace's service has ended, or its traffic is suspended |
500 | {"error": "..."} | The SMS provider rejected the message, or another server error |
{
"flowId": "b7b7b7b7b7b7b7b7b7b7b7b7",
"to": "+14155550123",
"metadata": {
"customerDetails": {
"name": "Sam"
}
}
}{
"status": "success",
"conversation_id": "b9b9b9b9b9b9b9b9b9b9b9b9",
"message_id": "b8b8b8b8b8b8b8b8b8b8b8b8",
"message": "Hi Sam, your appointment is confirmed for tomorrow at 3 PM.",
"channel": "Twilio-SMS"
} Last updated on