API Reference

Integrate EchoCue SMS messaging into your applications

Get API Key

Getting Started

The EchoCue API allows you to send SMS messages programmatically from your applications. All API requests require authentication using an API key.

Base URL

https://api.echocue.com:5501/v1

Authentication

All API requests must include your API key and API secret in the request headers. You can create and manage your API credentials from the API Keys page.

Required Headers

Authorization: Bearer <API_KEY>
X-API-SECRET: <API_SECRET>

Keep your API credentials secure

Never expose your API key or secret in client-side code or public repositories. Use environment variables or secure key management systems.

POST /notification/sms/api/send

Send an SMS message to a recipient

Request Headers

Header Required Description
Authorization Required Bearer token with your API key: Bearer <API_KEY>
X-API-SECRET Required Your EchoCue API secret
Content-Type Required Must be application/json

Request Body

Parameter Type Required Description
recipient_contact string Required The recipient's phone number in E.164 format (e.g., +14155551234)
message string Required The SMS message content (max 1600 characters). Required if template_id is not set
template_id string Optional The ID of the template that should be used to send the message: E.g. 74
variables string Optional Only required when template_id is used. This is a json : "variables": {"message": "Well done!!"}
recipient_name string Optional The recipient's name for logging purposes
schedule_time string Optional Schedule message for later delivery. Format: YYYY-MM-DD HH:MM:SS (24hr format). Assumed to be UTC unless timezone is specified
timezone string Optional IANA timezone for the schedule_time. If not specified, UTC is assumed. Examples: America/Bogota, America/New_York, Europe/London
device_id string Optional The ID of the device that should be used to send the message: E.g. 45 If not specified, first active device is selected

Code Examples

Basic Example (Direct Message)

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/sms/api/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "recipient_name": "John Doe",
    "message": "Hello from EchoCue! This is a test message.",
    "device_id": "45"
  }'

Using Template with Variables

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/sms/api/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "recipient_name": "Jane Smith",
    "template_id": "74",
    "variables": {"message": "Well done!!"},
    "device_id": "45"
  }'

Scheduled Message (UTC)

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/sms/api/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "recipient_name": "Mike Johnson",
    "message": "Reminder: Your appointment is tomorrow at 3 PM",
    "schedule_time": "2024-12-25 15:00:00",
    "device_id": "45"
  }'

Scheduled Message with Timezone

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/sms/api/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "recipient_name": "Mike Johnson",
    "message": "Reminder: Your appointment is tomorrow at 3 PM",
    "schedule_time": "2024-12-25 15:00:00",
    "timezone": "America/Bogota",
    "device_id": "45"
  }'

Response

Success Response (200 OK)

{
  "status_id": 200,
  "message": "Successfully scheduled sms notification",
  "data": {
    "notification_id": 12345,
    "template_id": null,
    "template_vars": null,
    "message": "Hello from EchoCue! This is a test message."
  }
}

Success Response with Template (200 OK)

{
  "status_id": 200,
  "message": "Successfully scheduled sms notification",
  "data": {
    "notification_id": 12345,
    "template_id": 74,
    "template_vars": { "message": "Well done!!" },
    "message": "Hi John, Well done!!"
  }
}

Error Response

{
  "status_id": 400,
  "message": "Invalid phone number format",
  "data": null
}

Error Codes

Status Code Description
200 Success - Message queued for delivery
400 Bad Request - Invalid parameters (check phone number format, message content)
401 Unauthorized - Invalid or missing API key or secret
402 Payment Required - Insufficient credits
403 Forbidden - API key is disabled or account is suspended
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Try again later
POST /notification/template/api/get

Retrieve message templates with variables for dynamic content

About Templates

Templates allow you to create reusable message formats with dynamic variables. Variables are defined using double curly braces like {{variable_name}}. When sending a message using a template, you provide values for these variables through the variables parameter in the Send SMS endpoint.

Request Headers

Header Required Description
Authorization Required Bearer token with your API key: Bearer <API_KEY>
X-API-SECRET Required Your EchoCue API secret
Content-Type Required Must be application/json

Request Body

Parameter Type Required Description
page integer Optional Page number for pagination (default: 1)
limit integer Optional Number of templates per page (default: 10, max: 100)

Code Examples

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/template/api/get' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response

Success Response (200 OK)

{
  "status_id": 200,
  "message": "Successfully fetched template(s)",
  "data": [
    {
      "template_id": 74,
      "template_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": 12,
      "code": "WELCOME_MSG",
      "name": "Welcome Message",
      "description": "Welcome new customers",
      "body": "Hi {{first_name}}, welcome to our service! Your account is now active.",
      "channel": "sms",
      "is_system": 0,
      "status": "active",
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-15 10:30:00"
    },
    {
      "template_id": 75,
      "template_guid": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "user_id": 12,
      "code": "ORDER_CONFIRM",
      "name": "Order Confirmation",
      "description": "Confirm order details",
      "body": "Order #{{order_id}} confirmed for {{customer_name}}. Total: ${{amount}}. Delivery: {{delivery_date}}.",
      "channel": "sms",
      "is_system": 0,
      "status": "active",
      "created_at": "2024-01-16 14:20:00",
      "updated_at": "2024-01-16 14:20:00"
    }
  ]
}

Error Response

{
  "status_id": 401,
  "message": "Invalid or missing API credentials",
  "data": []
}

Using Templates with Variables

Once you retrieve a template, you can use it to send messages by referencing its template_id and providing values for any variables defined in the template body.

Step 1: Identify Variables in Template

Variables in the template body are enclosed in double curly braces:

"body": "Hi {{first_name}}, welcome to our service!"

This template has one variable: first_name

Step 2: Send Message with Template

Use the Send SMS endpoint with template_id and variables:

{
  "recipient_contact": "+14155551234",
  "recipient_name": "John Doe",
  "template_id": "74",
  "variables": {
    "first_name": "John"
  },
  "device_id": "45"
}

Step 3: Message is Generated

The API automatically replaces variables with the provided values:

Template: "Hi {{first_name}}, welcome to our service!"

Result: "Hi John, welcome to our service!"

Important Notes

  • All variables in the template must be provided in the variables object
  • Variable names are case-sensitive: first_name ≠ First_Name
  • Variable names can only contain letters, numbers, and underscores
  • When using template_id, the message parameter is not required

Complete Example: Order Confirmation Workflow

Scenario

You want to send order confirmation messages to customers. The template has variables for order ID, customer name, amount, and delivery date.

1. Template Body

"Order #{{order_id}} confirmed for
{{customer_name}}. Total: ${{amount}}.
Delivery: {{delivery_date}}."

2. Variables Object

{
  "order_id": "12345",
  "customer_name": "Jane",
  "amount": "49.99",
  "delivery_date": "Jan 25"
}

Final Message Sent

"Order #12345 confirmed for Jane. Total: $49.99. Delivery: Jan 25."

Rate Limits

API requests are subject to rate limiting to ensure fair usage and system stability.

Requests per minute

60

Requests per day

10,000

If you need higher limits, please contact support.

Need Help?

If you have questions about the API or need assistance with your integration, we're here to help.

Contact Support Manage API Keys