API reference

Messages API

Send and list SMS messages through Ruut Voice.

Message resource

{
  "sid": "SM…",
  "account_sid": "AC…",
  "to": "+2348000000001",
  "from": "+2348000000002",
  "body": "Your verification code is 1234",
  "status": "queued",
  "direction": "outbound-api",
  "num_segments": "1",
  "date_created": "…",
  "uri": "/2010-04-01/Accounts/AC…/Messages/SM…"
}

Status values

queued → sending → sent → delivered, or terminal failed.

Send a message

POST/2010-04-01/Accounts/{AccountSid}/Messages

Parameter	Type	Description
`To` required	`string`	Destination number in E.164.
`From` required	`string`	Your Ruut Voice number in E.164. Either `From` or `MessagingServiceSid` is required.
`Body` required	`string`	Message text (max 1600 chars).
`MessagingServiceSid` optional	`string`	A messaging service to use instead of `From`.
`StatusCallback` optional	`string`	URL to receive message status webhooks.
`SmartEncoded` optional	`boolean`	Convert to GSM encoding when possible.
`ValidityPeriod` optional	`integer`	Seconds the message is valid (1–14400).
`SendAt` optional	`string`	Schedule the message for a future time (with `ScheduleType=fixed`).
`ScheduleType` optional	`string`	Set to `fixed` when scheduling with `SendAt`.

Example

curlbash

curl -X POST "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/Messages" \
  -u "$RUUT_ACCOUNT_SID:$RUUT_AUTH_TOKEN" \
  --data-urlencode "To=+2348000000001" \
  --data-urlencode "From=+2348000000002" \
  --data-urlencode "Body=Your verification code is 1234"

List messages

GET/2010-04-01/Accounts/{AccountSid}/Messages

Parameter	Type	Description
`To` optional	`string`	Filter by destination.
`From` optional	`string`	Filter by sender.
`Page` optional	`integer`	0-indexed page.
`PageSize` optional	`integer`	Records per page (max 1000).

Fetch a message

GET/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}

Return a single message resource.

Update a message

POST/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}

Update a message — typically to record a delivery failure or a price for billing reconciliation.

Parameter	Type	Description
`Status` optional	`string`	Delivery status (e.g. `sent`, `delivered`, `failed`).
`Price` optional	`string`	Cost of the message (for reconciliation).

Delete a message

DELETE/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}

Delete a message record. Use with care — the message is removed permanently.

Response — 204 No Content