Twilio API Documentation

Description

The Twilio SMS API enables developers to programmatically send SMS messages to mobile devices. This documentation provides detailed information on interacting with the Twilio SMS API, covering authentication, available endpoints, parameters, request and response examples, error codes, rate limiting, and code samples.

Authentication

To utilize the Twilio SMS API, authentication is required using your Twilio Account SID and Auth Token. Include these credentials in the request header for proper authentication.

Endpoints and Methods

1. Send SMS

  • Endpoint: /Messages
  • Method: POST
  • Description: Send an SMS message to a specified phone number.
  • Parameters:
    • To (string, required): The destination phone number.
    • From (string, required): Your Twilio phone number.
    • Body (string, required): The text content of the SMS.

Parameters

Header Parameters

  • Authorization (string, required): Basic authentication using Twilio Account SID and Auth Token.

Path Parameters

None

Query Parameters

None

Request Body Parameters

  • To (string, required): The recipient's phone number.
  • From (string, required): Your Twilio phone number.
  • Body (string, required): The content of the SMS.

Request

Send SMS (Curl)

curl -X POST -H "Authorization: Basic YOUR_TWILIO_AUTH" \
  -d "To=+1234567890" -d "From=+0987654321" -d "Body=Hello, this is a test message." \
  https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages

Response

Send SMS (Response Example)

{
  "status": "queued",
  "to": "+1234567890",
  "from": "+0987654321",
  "body": "Hello, this is a test message."
  // ... other response details
}

Send SMS (Response Schema)

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "to": { "type": "string" },
    "from": { "type": "string" },
    "body": { "type": "string" }
    // ... other properties
  }
}

Error Codes and Explanations

  • 400 Bad Request: Invalid request parameters.
  • 401 Unauthorized: Authentication failed.
  • 404 Not Found: Resource or endpoint not found.
  • 429 Too Many Requests: Rate limit exceeded.

Rate Limiting

Twilio SMS API imposes rate limits to prevent misuse. Refer to the Twilio Rate Limits Documentation and ensure compliance with the specified limits.

Code Samples

These code samples demonstrate how to send an SMS using the Twilio SMS API in Java, Python, and JavaScript. Make sure to replace placeholder values with your actual Twilio Account SID, Auth Token, and phone numbers. You can use these examples as a reference for integrating Twilio SMS functionality into your applications.

Java

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

public class TwilioSmsExample {
    public static final String ACCOUNT_SID = "YOUR_TWILIO_ACCOUNT_SID";
    public static final String AUTH_TOKEN = "YOUR_TWILIO_AUTH_TOKEN";

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

        Message message = Message.creator(
                new PhoneNumber("+1234567890"), // to
                new PhoneNumber("+0987654321"), // from
                "Hello, this is a test message."
        ).create();

        System.out.println("Message SID: " + message.getSid());
    }
}

Python

from twilio.rest import Client

account_sid = 'YOUR_TWILIO_ACCOUNT_SID'
auth_token = 'YOUR_TWILIO_AUTH_TOKEN'
client = Client(account_sid, auth_token)

message = client.messages.create(
    to='+1234567890',
    from_='+0987654321',
    body='Hello, this is a test message.'
)

print("Message SID:", message.sid)

JavaScript

const accountSid = 'YOUR_TWILIO_ACCOUNT_SID';
const authToken = 'YOUR_TWILIO_AUTH_TOKEN';
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    body: 'Hello, this is a test message.',
    from: '+0987654321',
    to: '+1234567890',
  })
  .then(message => console.log('Message SID:', message.sid));