Chat API

The Chat API allows you to send and receive WhatsApp messages programmatically. This guide covers the core functionality of the Chat API.

Sending Messages

Send a Text Message

// Send a simple text message
POST /api/v1/messages

{
  "to": "+1234567890",
  "type": "text",
  "text": "Hello from WhatsSync!"
}

Send an Image

// Send an image with caption
POST /api/v1/messages

{
  "to": "+1234567890",
  "type": "image",
  "image": {
    "url": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }
}

Send a Document

// Send a document
POST /api/v1/messages

{
  "to": "+1234567890",
  "type": "document",
  "document": {
    "url": "https://example.com/document.pdf",
    "filename": "report.pdf",
    "caption": "Monthly report"
  }
}

Send a Location

// Send a location
POST /api/v1/messages

{
  "to": "+1234567890",
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "San Francisco",
    "address": "San Francisco, CA"
  }
}

Message Templates

Message templates allow you to send structured messages that have been pre-approved by WhatsApp. This is especially useful for sending notifications and other non-conversational messages.

// Send a template message
POST /api/v1/messages

{
  "to": "+1234567890",
  "type": "template",
  "template": {
    "name": "appointment_reminder",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "June 10, 2023"
            }
          }
        ]
      }
    ]
  }
}

Retrieving Messages

Get Messages for a Contact

// Get messages for a specific contact
GET /api/v1/contacts/+1234567890/messages

// Response
{
  "messages": [
    {
      "id": "msg_123456",
      "from": "+1234567890",
      "to": "+0987654321",
      "type": "text",
      "text": "Hello!",
      "timestamp": "2023-06-15T14:22:30Z",
      "status": "delivered"
    },
    {
      "id": "msg_123457",
      "from": "+0987654321",
      "to": "+1234567890",
      "type": "text",
      "text": "Hi there!",
      "timestamp": "2023-06-15T14:23:15Z",
      "status": "read"
    }
  ],
  "pagination": {
    "next": "cursor_abcdef"
  }
}

Managing Contacts

List Contacts

// Get a list of contacts
GET /api/v1/contacts

// Response
{
  "contacts": [
    {
      "id": "contact_123456",
      "phone": "+1234567890",
      "name": "John Doe",
      "lastMessageAt": "2023-06-15T14:23:15Z"
    },
    {
      "id": "contact_123457",
      "phone": "+0987654321",
      "name": "Jane Smith",
      "lastMessageAt": "2023-06-14T10:15:30Z"
    }
  ],
  "pagination": {
    "next": "cursor_abcdef"
  }
}

Get Contact Details

// Get details for a specific contact
GET /api/v1/contacts/+1234567890

// Response
{
  "id": "contact_123456",
  "phone": "+1234567890",
  "name": "John Doe",
  "profileImage": "https://example.com/profile.jpg",
  "lastMessageAt": "2023-06-15T14:23:15Z",
  "tags": ["customer", "premium"]
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a message and error code for debugging.

// Example error response
{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number provided is not valid",
    "status": 400
  }
}

Rate Limits

The API has rate limits to prevent abuse. The current limits are:

• 60 requests per minute per API key
• 1000 messages per day per phone number

Rate limit information is included in the response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1623766980