Developers Docs

X Shape
X Shape

🔐 Authentication

All requests require a Bearer token in the header.

{
  "Authorization": "Bearer YOUR_API_TOKEN",
  "Content-Type": "application/json"
}

📥 Inboxes

GET /api/v1/inboxes

List all inboxes on the account.

POST /api/v1/inboxes

{
  "name": "Support",
  "channel": "WhatsApp",
  "phone_number": "+966500000000"
}

👥 Contacts

GET /api/v1/contacts

List all contacts.

POST /api/v1/contacts

{
  "name": "John Doe",
  "email": "john@company.com",
  "phone_number": "+123456789"
}

💬 Conversations

GET /api/v1/conversations

Returns a list of all conversations.

POST /api/v1/conversations

{
  "source_id": "CONTACT_ID",
  "inbox_id": "INBOX_ID"
}

📩 Messages

POST /api/v1/conversations/:id/messages

{
  "content": "Hello, how can I help you?",
  "message_type": "outgoing"
}

🧠 Custom Attributes

GET /api/v1/custom_attributes

PUT /api/v1/contacts/:id/custom_attributes

{
  "subscription_level": "premium"
}
$1

🔄 Webhooks

Subscribe to events like:

  • message.created
  • conversation.updated
  • contact.updated

Webhook Endpoint Configuration

Set your webhook URL in the DOO CX dashboard under Settings > Webhooks. The endpoint must be HTTPS.

Sample Webhook Payload

{
    "event": "message.created",
    "timestamp": 1699999999,
    "account_id": 1,
    "data": {
      "id": 123,
      "content": "Hello from DOO",
      "message_type": "incoming",
      "sender": {
        "id": 9,
        "name": "Customer"
      },
      "conversation": {
        "id": 999,
        "inbox_id": 2
      }
    }
  }

Available Webhook Events

  • conversation.created
  • conversation.updated
  • message.created
  • message.updated
  • contact.updated

Retry Mechanism

We retry failed webhook deliveries up to 10 times using exponential backoff. We recommend responding with 200 OK within 5 seconds.

Verifying Webhook Requests

Every webhook request includes an X-Signature header. You can verify it using HMAC SHA256 with your webhook secret:

// Node.js example
const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (req.headers['x-signature'] === signature) {
  // Valid
}

Webhook Endpoint Configuration

Set your webhook URL in the DOO CX dashboard under Settings > Webhooks. The endpoint must be HTTPS.

Sample Webhook Payload

{
  "event": "message.created",
  "timestamp": 1699999999,
  "account_id": 1,
  "data": {
    "id": 123,
    "content": "Hello from DOO",
    "message_type": "incoming",
    "sender": {
      "id": 9,
      "name": "Customer"
    },
    "conversation": {
      "id": 999,
      "inbox_id": 2
    }
  }
}

Available Webhook Events

Retry Mechanism

We retry failed webhook deliveries up to 10 times using exponential backoff. We recommend responding with 200 OK within 5 seconds.

Verifying Webhook Requests

Every webhook request includes an X-Signature header. You can verify it using HMAC SHA256 with your webhook secret:

// Node.js example
const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (req.headers['x-signature'] === signature) {
  // Valid
}

🛡️ Security & Rate Limits

  • 2,000 requests/min/token
  • Token expires after 90 days
  • All traffic over HTTPS