Developers Docs

🔐 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"
}

🔄 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
}