API Overview

The Chat24Plus REST API allows you to programmatically manage conversations, send messages, train your chatbot, and integrate with your existing systems.

Base URL

All API requests should be made to:

https://api.chat24plus.com/v1

Authentication

API Keys

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

1. Log in to your Chat24Plus Dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New API Key"
4. Give it a descriptive name (e.g., "Production Server")
5. Copy the key immediately (it won't be shown again)
6. Store it securely (environment variables recommended)

Security Warning

Never expose API keys in client-side code, public repositories, or version control. Treat them like passwords. If a key is compromised, revoke it immediately and generate a new one.

API Key Types

• Read-Only: Can only retrieve data (GET requests)
• Read-Write: Can send messages and modify data (GET, POST, PUT, PATCH)
• Full Access: Complete account control including settings (all methods)

Rate Limits

To ensure API stability, rate limits apply:

Plan	Requests/Minute	Requests/Hour	Requests/Day
Free	60	1,000	10,000
Starter	120	5,000	50,000
Business	300	20,000	200,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

Best Practices:

• Implement exponential backoff
• Cache responses when possible
• Batch requests where supported
• Monitor rate limit headers

Request Format

Content Type

All POST, PUT, and PATCH requests should use JSON:

Content-Type: application/json

Example Request

curl -X POST https://api.chat24plus.com/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_123abc",
    "message": "Hello! How can I help you today?",
    "channel": "whatsapp"
  }'

Response Format

Successful Response

{
  "success": true,
  "data": {
    "message_id": "msg_456def",
    "conversation_id": "conv_123abc",
    "status": "sent",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Conversation ID is required",
    "field": "conversation_id"
  }
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)
503	Service Unavailable	Temporary service disruption

Common Endpoints

Messages

POST   /messages/send          # Send a message
GET    /messages/:id           # Get message details
GET    /messages/search        # Search messages

Conversations

GET    /conversations          # List conversations
GET    /conversations/:id      # Get conversation details
POST   /conversations          # Create conversation
PATCH  /conversations/:id      # Update conversation
DELETE /conversations/:id      # Archive conversation

Contacts

GET    /contacts               # List contacts
GET    /contacts/:id           # Get contact details
POST   /contacts               # Create contact
PATCH  /contacts/:id           # Update contact
DELETE /contacts/:id           # Delete contact

Chatbot

POST   /chatbot/train          # Train chatbot with content
GET    /chatbot/status         # Get training status
POST   /chatbot/test           # Test chatbot response
GET    /chatbot/analytics      # Get chatbot metrics

Analytics

GET    /analytics/overview     # Get account overview
GET    /analytics/channels     # Channel performance
GET    /analytics/agents       # Agent performance
GET    /analytics/reports      # Generate custom report

Quick Start Examples

Send a Message

// Node.js
const fetch = require('node-fetch');

const sendMessage = async () => {
  const response = await fetch('https://api.chat24plus.com/v1/messages/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      conversation_id: 'conv_123abc',
      message: 'Hello from API!',
      channel: 'whatsapp'
    })
  });

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

sendMessage();

# Python
import requests

url = 'https://api.chat24plus.com/v1/messages/send'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {
    'conversation_id': 'conv_123abc',
    'message': 'Hello from API!',
    'channel': 'whatsapp'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

<?php
// PHP
$url = 'https://api.chat24plus.com/v1/messages/send';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];
$payload = [
    'conversation_id' => 'conv_123abc',
    'message' => 'Hello from API!',
    'channel' => 'whatsapp'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response));
?>

Get Conversations

// Node.js
const getConversations = async () => {
  const response = await fetch('https://api.chat24plus.com/v1/conversations?status=active&limit=10', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

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

getConversations();

Train Chatbot

# Python
import requests

url = 'https://api.chat24plus.com/v1/chatbot/train'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {
    'type': 'qa_pair',
    'question': 'What are your business hours?',
    'answer': 'We are open Monday-Friday, 9 AM - 6 PM EST.',
    'tags': ['hours', 'contact']
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Pagination

List endpoints support pagination:

Request

GET /conversations?page=2&limit=50

Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 250,
    "pages": 5,
    "has_next": true,
    "has_previous": true
  }
}

Filtering & Sorting

Most list endpoints support filtering and sorting:

GET /conversations?status=active&channel=whatsapp&sort=-created_at&limit=20

Common Filters:

• status: Filter by status (active, archived, etc.)
• channel: Filter by channel (whatsapp, telegram, etc.)
• agent_id: Filter by assigned agent
• created_after: Filter by creation date
• created_before: Filter by creation date

Sorting:

• Use sort parameter with field name
• Prefix with - for descending order
• Example: sort=-created_at (newest first)

Webhooks

Receive real-time notifications for events. See Webhooks Documentation for details.

SDKs & Libraries

Official SDKs available for:

• JavaScript/Node.js: npm install @chat24plus/sdk
• Python: pip install chat24plus
• PHP: composer require chat24plus/sdk
• Ruby: gem install chat24plus

See SDK Documentation for usage guides.

Testing

Sandbox Environment

Test your integration without affecting production:

https://sandbox-api.chat24plus.com/v1

• Separate API keys for sandbox
• Test data doesn't affect production
• All features available
• Rate limits still apply

Postman Collection

Download our Postman Collection with pre-configured requests for all endpoints.

Best Practices

Error Handling

const makeRequest = async () => {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();
      console.error('API Error:', error);
      // Handle specific error codes
      if (error.code === 'rate_limit_exceeded') {
        // Implement retry logic
      }
      return;
    }

    const data = await response.json();
    // Process successful response
  } catch (error) {
    console.error('Network Error:', error);
  }
};

Security

• Store API keys in environment variables
• Use HTTPS for all requests
• Rotate API keys regularly
• Implement IP whitelisting (Enterprise plans)
• Monitor API usage for anomalies

Performance

• Cache responses when appropriate
• Use pagination for large datasets
• Implement connection pooling
• Compress request/response bodies
• Use webhooks instead of polling

Versioning

The API is versioned through the URL path (/v1/). We maintain backward compatibility within major versions.

Version History:

• v1 - Current (Released: January 2024)

Breaking changes will be announced 90 days in advance via:

• Email notifications
• Dashboard announcements
• Changelog

Support

Resources

• API Reference - Complete endpoint documentation
• Webhooks Guide - Real-time event notifications
• Code Examples - Integration examples
• SDKs - Official client libraries

Getting Help

• API Status: status.chat24plus.com
• Email: [email protected]
• Developer Discord: discord.gg/chat24plus
• GitHub Issues: github.com/chat24plus/api-issues

---

Ready to build? Check out our detailed API Reference or explore code examples.