📚 AmanahAgent Docs
API Playground

API Reference

Complete reference for the AmanahAgent WhatsApp Business API. Integrate messaging capabilities into your applications.

API Overview

🌐 Base URL

https://api.amanahagent.cloud/v1

All API requests should use HTTPS

🔑 Authentication

Bearer token authentication required

Authorization: Bearer YOUR_API_KEY

⚡ Rate Limits

Free Plan: 100 requests/hour
Pro Plan: 1,000 requests/hour
Enterprise: 10,000 requests/hour

Messages API

Send Message

POST /messages

Send a WhatsApp message to a recipient.

Request Parameters

ParameterTypeRequiredDescription
tostringRequiredRecipient phone number with country code
typestringRequiredMessage type: text, media, template
messagestringOptionalMessage text content (required for text messages)
media_urlstringOptionalURL for media messages (image, video, document)
template_idstringOptionalTemplate ID for template messages

Example Request

JavaScript
const response = await fetch('https://api.amanahagent.cloud/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+1234567890',
    type: 'text',
    message: 'Hello from AmanahAgent!'
  })
});

const data = await response.json();
console.log(data);
Python
import requests

response = requests.post('https://api.amanahagent.cloud/v1/messages', 
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  json={
    'to': '+1234567890',
    'type': 'text',
    'message': 'Hello from AmanahAgent!'
  }
)

data = response.json()
print(data)
PHP
<?php
$ch = curl_init('https://api.amanahagent.cloud/v1/messages');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+1234567890',
  'type' => 'text',
  'message' => 'Hello from AmanahAgent!'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer YOUR_API_KEY',
  'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

print_r($data);
?>

Example Response

{
  "message_id": "msg_abc123xyz789",
  "status": "sent",
  "to": "+1234567890",
  "type": "text",
  "timestamp": "2024-01-15T10:30:00Z",
  "credits_used": 1,
  "delivery_status": "pending"
}

Get Message Status

GET /messages/{message_id}

Retrieve the delivery status and details of a sent message.

Example Response

{
  "message_id": "msg_abc123xyz789",
  "status": "delivered",
  "to": "+1234567890",
  "type": "text",
  "message": "Hello from AmanahAgent!",
  "sent_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:15Z",
  "read_at": null,
  "credits_used": 1
}

Contacts API

Create Contact

POST /contacts

Add a new contact to your address book.

Request Parameters

ParameterTypeRequiredDescription
phonestringRequiredPhone number with country code
namestringOptionalContact's full name
tagsarrayOptionalTags for organizing contacts
custom_fieldsobjectOptionalCustom field values

Example Request

{
  "phone": "+1234567890",
  "name": "John Doe",
  "tags": ["customer", "premium"],
  "custom_fields": {
    "company": "Acme Corp",
    "department": "Sales"
  }
}

List Contacts

GET /contacts

Retrieve a paginated list of your contacts.

Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger50Number of contacts per page (max 100)
searchstring-Search by name or phone
tagsstring-Filter by tags (comma-separated)

Media API

Upload Media

POST /media

Upload images, videos, documents, or audio files to use in messages.

Supported formats: Images (JPG, PNG, GIF), Videos (MP4, 3GP), Documents (PDF, DOC, XLS, PPT), Audio (MP3, OGG, AMR)

Request Parameters

ParameterTypeRequiredDescription
filefileRequiredMedia file (max 16MB)
filenamestringOptionalCustom filename

Example Request (JavaScript)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('filename', 'custom-name.jpg');

const response = await fetch('https://api.amanahagent.cloud/v1/media', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const data = await response.json();
console.log(data);

Example Response

{
  "media_id": "media_xyz789abc123",
  "url": "https://cdn.amanahagent.cloud/media/xyz789abc123.jpg",
  "filename": "custom-name.jpg",
  "content_type": "image/jpeg",
  "size": 245760,
  "created_at": "2024-01-15T10:30:00Z"
}

Templates API

Create Template

POST /templates

Create a message template for reuse. Templates must be approved by WhatsApp before use.

Request Parameters

ParameterTypeRequiredDescription
namestringRequiredTemplate name (lowercase, underscore separated)
languagestringRequiredLanguage code (e.g., "en", "ar")
categorystringRequiredCategory: MARKETING, UTILITY, AUTHENTICATION
componentsarrayRequiredTemplate components (header, body, footer, buttons)

Example Request

{
  "name": "welcome_message",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Welcome to {{1}}"
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}, thanks for joining us! Your account is now active."
    },
    {
      "type": "FOOTER",
      "text": "AmanahAgent Team"
    }
  ]
}

List Templates

GET /templates

Retrieve all your message templates with their approval status.

Example Response

{
  "templates": [
    {
      "id": "tpl_abc123xyz789",
      "name": "welcome_message",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "created_at": "2024-01-10T10:30:00Z",
      "approved_at": "2024-01-12T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

Webhooks API

Configure Webhook

POST /webhooks

Configure webhook endpoints to receive real-time updates about message status, delivery receipts, and incoming messages.

Request Parameters

ParameterTypeRequiredDescription
urlstringRequiredHTTPS URL to receive webhook events
eventsarrayRequiredEvent types to subscribe to
secretstringOptionalSecret for webhook signature verification

Available Events

  • message.sent - Message successfully sent
  • message.delivered - Message delivered to recipient
  • message.read - Message read by recipient
  • message.failed - Message delivery failed
  • message.received - Incoming message from user

Example Request

{
  "url": "https://your-app.com/webhooks/amanahagent",
  "events": [
    "message.sent",
    "message.delivered",
    "message.read",
    "message.received"
  ],
  "secret": "your-webhook-secret"
}

Webhook Payload Example

{
  "event": "message.delivered",
  "timestamp": "2024-01-15T10:30:15Z",
  "data": {
    "message_id": "msg_abc123xyz789",
    "status": "delivered",
    "to": "+1234567890",
    "delivered_at": "2024-01-15T10:30:15Z"
  }
}

Analytics API

Get Usage Statistics

GET /analytics/usage

Retrieve usage statistics and metrics for your account.

Query Parameters

ParameterTypeDefaultDescription
periodstring7dTime period: 1d, 7d, 30d, 90d
start_datestring-Custom start date (YYYY-MM-DD)
end_datestring-Custom end date (YYYY-MM-DD)

Example Response

{
  "period": "7d",
  "start_date": "2024-01-08",
  "end_date": "2024-01-15",
  "metrics": {
    "messages_sent": 1250,
    "messages_delivered": 1180,
    "messages_read": 950,
    "messages_failed": 70,
    "delivery_rate": 94.4,
    "read_rate": 80.5,
    "credits_used": 1250,
    "unique_contacts": 485
  },
  "daily_breakdown": [
    {
      "date": "2024-01-15",
      "messages_sent": 180,
      "messages_delivered": 175,
      "credits_used": 180
    }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON object with error details.

HTTP Status Codes

CodeStatusDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

Error Response Format

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The phone number format is invalid",
    "details": {
      "field": "to",
      "value": "invalid-number"
    }
  }
}

Getting Started

Set up your account and API keys

Quick Start

Send your first message in 5 minutes

Webhooks Guide

Set up real-time notifications

SDK Documentation

Language-specific libraries