Skip to main content

​
Overview

Our messaging API allows you to send both SMS (text) and MMS (multimedia) messages programmatically. Messages are queued and delivered through your configured messaging provider.

​
Basic SMS message

The simplest way to send a message requires just two parameters: 
const message = await sendMessage({
  to: '+15551234567',
  body: 'Hello world!'
});

​
Specifying a sender

By default, messages are sent from your configured messaging service number. You can specify a different sender number: 
const message = await sendMessage({
  to: '+15551234567',
  from: '+15559876543',
  body: 'Hello from a specific number!'
});
The from number must be configured in your workspace and verified with your messaging provider.

​
Sending to multiple recipients

To send messages to multiple recipients, make parallel API calls: 
const recipients = ['+15551234567', '+15557654321', '+15555555555'];

const promises = recipients.map(to =>
  sendMessage({
    to,
    body: 'Broadcast message to multiple recipients'
  })
);

const results = await Promise.all(promises);

​
Long messages

SMS messages longer than 160 characters are automatically split into multiple segments:
  • Single SMS: Up to 160 characters
  • Multi-part SMS: Up to 1,600 characters (split into segments of 153 characters each)
Carriers charge for each message segment. A 300-character message counts as 2 SMS messages.

​
MMS messages

To send multimedia messages, include media URLs: 
const message = await sendMessage({
  to: '+15551234567',
  body: 'Check out this image!',
  mediaUrl: 'https://example.com/image.jpg'
});
Supported media types:
  • Images: JPEG, PNG, GIF (up to 5MB)
  • Audio: MP3, WAV (up to 5MB)
  • Video: MP4, 3GP (up to 5MB)
  • Documents: PDF, VCF (up to 5MB)

​
Message status

All messages start with a queued status and progress through these states:
StatusDescription
queuedMessage accepted and queued for delivery
sendingMessage is being sent to carrier
sentMessage sent to carrier network
deliveredMessage confirmed delivered to device
failedMessage could not be delivered
undeliveredMessage sent but not delivered

​
Error handling

Always implement proper error handling: 
try {
  const message = await sendMessage({
    to: '+15551234567',
    body: 'Hello world!'
  });
  console.log('Message sent:', message.sid);
} catch (error) {
  if (error.status === 400) {
    console.error('Invalid request:', error.message);
  } else if (error.status === 401) {
    console.error('Authentication failed');
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Best practices

  1. Validate phone numbers: Always validate and format phone numbers in E.164 format (+country code + number)
  2. Handle rate limits: Implement exponential backoff for rate limit errors
  3. Log message SIDs: Store the message SID for tracking and debugging
  4. Use callbacks: Set up webhooks to receive real-time delivery updates
  5. Test thoroughly: Test with different carriers and number types

​
Examples

​
Send a reminder

async function sendReminder(phoneNumber, appointmentTime) {
  return await sendMessage({
    to: phoneNumber,
    body: `Reminder: Your appointment is scheduled for ${appointmentTime}. Reply CONFIRM to confirm or CANCEL to cancel.`
  });
}

​
Send a verification code

async function sendVerificationCode(phoneNumber, code) {
  return await sendMessage({
    to: phoneNumber,
    body: `Your verification code is: ${code}. This code expires in 10 minutes.`
  });
}

​
Send a marketing message

async function sendPromotion(phoneNumber, promoCode) {
  return await sendMessage({
    to: phoneNumber,
    body: `🎉 Special offer! Use code ${promoCode} for 20% off your next order. Reply STOP to unsubscribe.`
  });
}

​
Next steps