Skip to content
OnCoreDocs

Messaging & channels

Send an SMS

Text someone from a phone number registered on your tenant, with your own message body.

POST /sms sends one text from a phone number you already have on OnCore. You choose the recipient and the body. This is separate from the SMS channel, where the assistant answers inbound texts on its number, and from SMS reasons, where the assistant texts someone during a voice call.

Overview#

Use this when your own server needs to send a text, for example to tell a person that a caller tried to reach them and nobody answered. The message goes out from a number registered on the same tenant as your API key. OnCore refuses a number that belongs to another tenant.

Prerequisites#

The fromNumber must already be a phone number on your tenant. Buy or import it with the phone numbers API first. A deleted number cannot send.

Send a message#

Terminal
curl -X POST https://core-api.heysadie.ai/sms \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+15555550123",
    "toNumber": "+15555550999",
    "message": "A caller tried to reach your team and nobody answered."
  }'
FieldRequiredDescription
fromNumberYesE.164 number registered on your tenant, for example +15555550123.
toNumberYesE.164 recipient.
messageYesThe SMS body. It cannot be empty, and it cannot be longer than 1600 characters.

Both numbers must include the leading + and the country code. A local number such as 5551234 is rejected.

What you get back#

A successful send returns the standard response envelope. data.messageSid is the identifier of the text that went out. Keep it if you need to reconcile delivery later.

200 response
{
  "success": true,
  "data": {
    "messageSid": "SM123"
  },
  "metadata": {
    "timestamp": "2026-09-22T12:00:00.000Z",
    "version": "1.0",
    "path": "/sms"
  }
}

Failures#

StatusCodeWhen
400VALIDATION_ERRORA number is not E.164, the body is empty, or the body is longer than 1600 characters. error.details names the field.
401UNAUTHORIZEDThe Authorization header is missing or is not a valid API key.
404RESOURCE_NOT_FOUNDfromNumber is unknown, deleted, or registered on another tenant. Those three cases return the same 404, so a response does not reveal whether the number exists.
502SMS_SEND_FAILEDOnCore accepted the request and then the text could not be sent. The message body is not echoed back.

The 404 uses the normal error envelope. It is not the bare { "error": "not_found" } body used by the embed endpoints.

Limits#

  • One request sends one text to one recipient. To reach several people, send one request per number.
  • The body limit is 1600 characters.
  • You can only send from a number on your own tenant.

Next steps#

  • SMS API: the generated reference for POST /sms.
  • SMS: the assistant answers inbound texts on its number.
  • SMS reasons: texts sent during a voice call.
  • Phone numbers: register the number you send from.
PreviousWhatsAppNextIntroduction