Developer
Manage API keys and integrate EchoCue into your applications
Your API Keys
Create and manage API keys for programmatic access
| Name | API Key | Status | Created | Actions |
|---|---|---|---|---|
|
Loading API keys...
|
||||
Base URL
All API requests should be made to the following 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 tab.
Required Headers
Authorization: Bearer <API_KEY> X-API-SECRET: <API_SECRET> Content-Type: application/json
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.
/api/device/list
List all devices with pagination
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number (default: 1) |
limit |
integer | Optional | Items per page (default: 20, max: 100) |
status |
string | Optional | Filter by status: active, inactive |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/device/list?page=1&limit=20' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"message": "Success",
"data": {
"devices": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 45
}
}
}
/api/device/export
Export devices as CSV or JSON
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
format |
string | Optional | Export format: csv, json (default: json) |
include_inactive |
boolean | Optional | Include inactive devices (default: false) |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/device/export?format=csv' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/device/:device_id
Get single device details
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id |
integer | Required | The unique device identifier |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/device/123' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"data": {
"device_id": 123,
"name": "My Device",
"status": "active"
}
}
/api/device/:device_id/health
Get device health status
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/device/123/health' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"data": {
"health_score": 95,
"last_sync": "2024-01-15T10:30:00Z"
}
}
/api/device/:device_id/stats
Get device performance statistics
Success Response
{
"status_id": 200,
"data": {
"sent": 1250,
"failed": 15,
"pending": 5
}
}
/api/device/:device_id/usage
Get device usage against plan limits
Success Response
{
"status_id": 200,
"data": {
"used": 500,
"limit": 1000,
"remaining": 500
}
}
/api/device/:device_id/rate-limit
Get current rate limit status
Success Response
{
"status_id": 200,
"data": {
"requests_remaining": 55,
"reset_at": "2024-01-15T10:31:00Z"
}
}
/api/device/batch/register
Batch register devices (max 10)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
devices |
array | Required | Array of device objects to register (max 10) |
/api/device/batch/delete
Batch delete devices (max 50)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
device_ids |
array | Required | Array of device IDs to delete (max 50) |
/api/device/batch/update-status
Batch activate/deactivate devices
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
device_ids |
array | Required | Array of device IDs |
status |
string | Required | New status: active, inactive |
/api/project/list
List all workspaces
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/project/list' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"data": {
"projects": [
{
"project_id": 1,
"name": "My Workspace",
"created_at": "2024-01-01T00:00:00Z"
}
]
}
}
/api/contact/list
List contacts with pagination
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number (default: 1) |
limit |
integer | Optional | Items per page (default: 20, max: 100) |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/contact/list?page=1&limit=20' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/contact/:contact_id
Get single contact with details
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/contact/456' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/contact/types
Get all contact types
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/contact/types' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/contact/search
Search contacts by name/details
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Required | Search query string |
/api/contact/create
Create new contact
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Required | Contact name |
phone |
string | Required | Phone number in E.164 format |
email |
string | Optional | Email address |
/api/contact/update
Update existing contact
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
contact_id |
integer | Required | Contact ID to update |
/api/contact/delete
Delete contact
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
contact_id |
integer | Required | Contact ID to delete |
/api/template/list
List templates with pagination
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel |
string | Optional | Filter by channel: sms, whatsapp |
page |
integer | Optional | Page number (default: 1) |
limit |
integer | Optional | Items per page (default: 20) |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/template/list?channel=sms' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/template/:template_id
Get single template
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/template/74' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/notification/list
List notifications with filtering
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status |
string | Optional | Filter by status: pending, sent, delivered, failed |
delivery_type |
string | Optional | Filter by type: sms, whatsapp |
/api/notification/:notification_id
Get notification details
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/notification/12345' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/notification/cancel
Cancel pending notification
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
notification_id |
integer | Required | ID of the notification to cancel |
/api/thread/list
List message threads
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/thread/list' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/thread/:thread_id/messages
Get messages for a thread
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/thread/789/messages' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
/api/sms/send
Send SMS message (supports templates with variables)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
recipient_contact |
string | Required | Phone number in E.164 format |
message |
string | Required* | Message content (required if template_id not set) |
template_id |
string | Optional | Template ID to use |
variables |
object | Optional | Template variables |
Example Request
curl -X POST \ 'https://api.echocue.com:5501/v1/api/sms/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", "message": "Hello from EchoCue!" }'
/api/sms/send/bulk
Send bulk SMS (max 100 messages)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
messages |
array | Required | Array of message objects (max 100) |
/api/whatsapp/send
Send WhatsApp message
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
recipient_contact |
string | Required | WhatsApp phone number |
message |
string | Required | Message content |
Example Request
curl -X POST \ 'https://api.echocue.com:5501/v1/api/whatsapp/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", "message": "Hello via WhatsApp!" }'
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."
}
}
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 |
/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 }'
const getTemplates = async () => { const response = await fetch( 'https://api.echocue.com:5501/v1/notification/template/api/get', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your_api_key_here', 'X-API-SECRET': 'your_api_secret_here' }, body: JSON.stringify({ page: 1, limit: 10 }) } ); const data = await response.json(); console.log(data); };
import requests import json url = "https://api.echocue.com:5501/v1/notification/template/api/get" headers = { "Content-Type": "application/json", "Authorization": "Bearer your_api_key_here", "X-API-SECRET": "your_api_secret_here" } payload = { "page": 1, "limit": 10 } response = requests.post(url, headers=headers, data=json.dumps(payload)) print(response.json())
<?php $url = 'https://api.echocue.com:5501/v1/notification/template/api/get'; $headers = [ 'Content-Type: application/json', 'Authorization: Bearer your_api_key_here', 'X-API-SECRET: your_api_secret_here' ]; $data = [ 'page' => 1, 'limit' => 10 ]; $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); $response = curl_exec($ch); curl_close($ch); print_r(json_decode($response, true)); ?>
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!",
"channel": "sms",
"is_system": 0,
"status": "active",
"created_at": "2024-01-15 10:30:00",
"updated_at": "2024-01-15 10:30:00"
}
]
}
/api/stats/notifications
Get notification statistics
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
period |
string | Optional | Time period: day, week, month |
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/stats/notifications?period=week' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"data": {
"sent": 1250,
"delivered": 1200,
"failed": 50,
"pending": 25
}
}
/api/stats/credits
Get credit balance
Example Request
curl -X GET \ 'https://api.echocue.com:5501/v1/api/stats/credits' \ -H 'Authorization: Bearer your_api_key_here' \ -H 'X-API-SECRET: your_api_secret_here'
Success Response
{
"status_id": 200,
"data": {
"balance": 5000,
"used_this_month": 1250
}
}
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.