API Reference Documentation

Manage contacts, send messages, and subscribe to webhook events.

Authentication

All requests require a Bearer token in the Authorization header. Generate tokens on the API Tokens page.

Authorization: Bearer YOUR_API_TOKEN

Base URL

https://www.app.ochats.io/api/v1

Content Type

Content-Type: application/json

Rate Limit

60 requests / minute / token

Response Envelope

Success (2xx)

{ "success": true, "data": { ... }, "message": "..." }

Error (4xx / 5xx)

{ "success": false, "message": "Error description." }

Contacts

GET/contacts/search: Search contacts

POST/contacts: Create a contact

PUT/contacts/{id}: Update a contact

POST/contacts/{id}/tags: Add tags to a contact

GET/contacts/{id}/channels: Get contact channels

Messages

Channel Provider IDs:

1=WhatsApp Gupshup, 5=Facebook, 6=Instagram, 7=Telegram, 8=LINE, 11=Email, 12=WhatsApp Cloud API, 14=WeChat.

Use GET /contacts/{id}/channels to discover which channels a contact has.

POST/messages: Send a text message

POST/messages/template: Send a template message

POST/messages/attachment: Send an attachment

POST/messages/quick-replies: Send quick replies

GET/messages/{id}: Get a message

Webhooks

Manage webhook subscriptions via API or from the Webhooks UI. Each subscription listens for one trigger_type.

GET/webhooks: List webhook subscriptions

POST/webhooks: Create a webhook subscription

GET/webhooks/{id}: Get a webhook subscription

PUT/webhooks/{id}: Update a webhook subscription

DELETE/webhooks/{id}: Delete a webhook subscription

GET/webhooks/{id}/logs: Get delivery logs

POST/webhooks/{id}/test: Send a test event

Custom Fields & Profiles

GET/custom-fields: List custom fields

PUT/profiles/{id}: Update a profile

Webhook Events & Payloads

When an event occurs, oChats sends a POST request to your URL with a JSON body. Every payload includes event, workspace_id, and timestamp. Click an event to see its full example payload.

contact.created: A new contact was created in the workspace

contact.updated: Contact details were modified

conversation.opened: A conversation was opened or re-opened

conversation.closed: A conversation was marked as closed

contact.tag_updated: A tag was applied to a contact

contact.assignee_updated: Contact was assigned to a different agent

message.incoming: A new message was received from a contact

message.outgoing: A message was sent to a contact

whisper.created: An internal note (whisper) was added to the conversation

Signature Verification

When a subscription has a secret, every delivery includes the header:

X-OChats-Signature-256: sha256=<hmac-sha256-hex>

The HMAC is computed over the raw request body using your secret as the key.

PHP

$payload   = file_get_contents('php://input');
$header    = $_SERVER['HTTP_X_OCHATS_SIGNATURE_256'] ?? '';
$signature = ltrim($header, 'sha256=');
$expected  = hash_hmac('sha256', $payload, $your_secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, header, secret) {
  const signature = header.replace('sha256=', '');
  const expected  = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Error Reference

Status	Meaning	Example
401	Invalid or missing API token	{"message": "Unauthenticated."}
403	Token lacks access to this workspace	{"success": false, "message": "Forbidden"}
404	Resource not found or belongs to another workspace	{"success": false, "message": "No Data Found."}
422	Validation error — missing or invalid parameters	{"message": "The name field is required.", "errors": {...}}
429	Rate limit exceeded (60 requests / minute)	{"message": "Too Many Attempts."}
500	Unexpected server error	{"success": false, "message": "Something Went Wrong."}