Send an SMS for a communication

POST

/v1/internal/sms/send

curl --request POST \
  --url https://example.com/v1/internal/sms/send \
  --header 'Content-Type: application/json' \
  --data '{ "communication_sid": "example", "provider_sid": "example", "from_alpha": "example", "from_number": "example", "to": "example", "text": "example", "variables": { "additionalProperty": "example" } }'

The shared send contract on the internal (VPN) surface: resolves the target, renders the provider request, executes it (10s timeout), and records the attempt. Provider-call failures return 200 with status “failed” — the attempt is recorded either way. Called by the hermes SMS brick runner with an explicit recipient.

Request Body^required

Media typeapplication/json

One send contract for both zones. Exactly one of communication_sid (resolve the agent’s provider and sender from that communication) or provider_sid (direct send: at least one of from_alpha/from_number — registered senders of that provider, from_alpha preferred when both are set) must be set. With communication_sid the sender comes from the agent’s SMS settings. to is always explicit — the caller states the recipient.

object

communication_sid

string

provider_sid

string

from_alpha

Direct sends: one of the provider’s registered alphas. At least one of from_alpha/from_number is required with provider_sid; from_alpha wins when both are set.

string

from_number

Direct sends: one of the provider’s registered numbers. At least one of from_alpha/from_number is required with provider_sid; from_alpha wins when both are set.

string

to

required

string

text

required

string

variables

Values for additional {{name}} template variables in the provider config. The reserved from/to/text variables always win over a same-named entry.

object

key

additional properties

string

Example^generated

{
  "communication_sid": "example",
  "provider_sid": "example",
  "from_alpha": "example",
  "from_number": "example",
  "to": "example",
  "text": "example",
  "variables": {
    "additionalProperty": "example"
  }
}

Responses

200

Send attempt recorded.

Media typeapplication/json

object

id

required

The recorded sms row id (sms_…).

string

status

required

string

Allowed values: sent failed

from

required

The resolved sender identity the message was sent as.

string

to

required

The resolved recipient.

string

http_status

required

Provider response status; null when no response was received.

integer

nullable

error

required

string

nullable

Example

{
  "status": "sent"
}

400

Malformed request.

404

Unknown communication.

422

Agent has no SMS settings, or the provider is missing or inactive.