Skip to main content
POST
Send an outbound SMS from an agent's connected number

Example — direct send

Example — AI-generated opener (mode: agent)

to and optional from must be E.164 (+ and country code). The agent must have an SMS-capable Twilio number connected (own account or platform rental).
Use options.dryRun: true to validate routing (from number, mode, segment count) without sending.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
agentId
string
required

Agent ID whose connected SMS number will send the message.

Minimum string length: 1
to
string
required

Recipient phone number in E.164 format, e.g. +15551234567.

Pattern: ^\+
from
string

Specific connected Twilio number to send from. Defaults to the agent's primary SMS number.

Pattern: ^\+
message
string

Message body for direct mode. Required unless mode is agent and initialPrompt is provided via options.

mediaUrl
string<uri>

Single MMS media URL.

mediaUrls
string<uri>[]

Multiple MMS media URLs (Twilio supports up to 10).

Maximum array length: 10
mode
enum<string>
default:direct

direct = send the message as-is. agent = run the agent first and send its generated reply.

Available options:
direct,
agent
campaignId
string

Optional campaign ID to attach to the outbound SMS conversation.

convoId
string

Custom conversation ID. Defaults to the normalized recipient phone number digits.

leadInfo
object

Lead metadata merged into the conversation for personalization.

options
object

Advanced options for outbound SMS delivery and conversation handling.

Response

Successful response

success
boolean
required
status
string
dryRun
boolean
skipped
boolean
reason
string
agentId
string
to
string
from
string
convoId
string
mode
enum<string>
Available options:
direct,
agent
senderMode
enum<string>
Available options:
own_account,
platform_rental
campaignId
string
messageSid
string
messageSids
string[]
messageCount
number
mediaCount
number
messagesPreview
string[]
segments
object[]