Send SMS

Send an SMS message using your phone number

POST /user/sms

Send SMS

cURL

curl --request POST \
  --url https://app.voicery.ai/api/user/sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": 123,
  "to": "<string>",
  "body": "<string>"
}
'

201 Success Response

{
  "message": "SMS sent successfully",
  "data": {
    "id": 456,
    "phone_number_id": 78,
    "to": "[phone]",
    "body": "Hello! This is a test message from Your Company. How can we help you today?",
    "user_id": 1,
    "segments": 1,
    "segment_price": 0.0075,
    "total_cost": 0.0075,
    "status": "sent",
    "sms_sid": "SM1234567890abcdef1234567890abcdef",
    "created_at": "2025-08-04 15:30:00",
    "updated_at": "2025-08-04 15:30:02"
  }
}

This endpoint allows you to send SMS messages using your purchased phone numbers. The SMS will be sent via Twilio and costs will be automatically deducted from your account balance.

Request Body

from · integer · required

The ID of your phone number to send the SMS from (must be SMS-capable)

to · string · required

The recipient’s phone number in international format (e.g., “[phone]”)

body · string · required

The SMS message content (max 300 characters)

Response

message · string

Success message confirming SMS was sent

data · object

Show properties

id · integer

The unique identifier of the SMS record

phone_number_id · integer

The ID of the phone number used to send the SMS

to · string

The recipient’s phone number in E.164 format

body · string

The SMS message content

user_id · integer

The ID of the user who sent the SMS

segments · integer

Number of SMS segments (for billing purposes)

segment_price · number

Cost per SMS segment

total_cost · number

Total cost of the SMS (segment_price * segments)

status · string

The current status of the SMS

sms_sid · string

Twilio SMS SID for tracking

created_at · string

The date and time when the SMS was created

updated_at · string

The date and time when the SMS was last updated

Error Responses

400 Bad Request

Show Error Response

message · string

Error message describing the issue (invalid phone number, insufficient balance, etc.)

500 Internal Server Error

Show Error Response

message · string

Error message indicating SMS sending failure

error · string

Detailed error information

201 Success Response

{
  "message": "SMS sent successfully",
  "data": {
    "id": 456,
    "phone_number_id": 78,
    "to": "[phone]",
    "body": "Hello! This is a test message from Your Company. How can we help you today?",
    "user_id": 1,
    "segments": 1,
    "segment_price": 0.0075,
    "total_cost": 0.0075,
    "status": "sent",
    "sms_sid": "SM1234567890abcdef1234567890abcdef",
    "created_at": "2025-08-04 15:30:00",
    "updated_at": "2025-08-04 15:30:02"
  }
}

Notes

• The sender phone number must belong to the authenticated user
• The sender phone number must be SMS-capable
• The phone number subscription must be active (not expired)
• Sufficient account balance is required to cover SMS costs
• Phone numbers are automatically formatted to E.164 format
• SMS costs vary by destination country and are charged per segment
• Long messages may be split into multiple segments, increasing the cost
• The recipient phone number must be valid according to international standards