{ "openapi": "3.1.0", "info": { "title": "ChatMaxima API", "version": "2.0.0", "description": "REST API for ChatMaxima: send messages on WhatsApp, Instagram, Messenger, Telegram, SMS, email and web chat; send WhatsApp templates; receive WhatsApp webhooks; manage contacts; export conversations. Every path ends with a trailing slash. API access requires a Pro, Max, Ultra or Enterprise plan.", "contact": { "name": "ChatMaxima", "url": "https://chatmaxima.com/" } }, "externalDocs": { "description": "ChatMaxima API documentation", "url": "https://docs.chatmaxima.com/api" }, "servers": [ { "url": "https://chatmaxima.com/api/v2" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Messages", "externalDocs": { "url": "https://docs.chatmaxima.com/api/send-messages" } }, { "name": "WhatsApp Templates", "externalDocs": { "url": "https://docs.chatmaxima.com/api/whatsapp-templates" } }, { "name": "WhatsApp Messages", "externalDocs": { "url": "https://docs.chatmaxima.com/api/whatsapp-messages" } }, { "name": "WhatsApp Webhooks", "externalDocs": { "url": "https://docs.chatmaxima.com/api/whatsapp-webhooks" } }, { "name": "Channel Accounts", "externalDocs": { "url": "https://docs.chatmaxima.com/api/channel-accounts" } }, { "name": "Media", "externalDocs": { "url": "https://docs.chatmaxima.com/api/media" } }, { "name": "Contacts", "externalDocs": { "url": "https://docs.chatmaxima.com/api/contacts" } }, { "name": "Conversations", "externalDocs": { "url": "https://docs.chatmaxima.com/api/conversations-export" } } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your workspace API key as the raw header value, with no Bearer prefix. Find it at https://chatmaxima.com/developer/settings/." } }, "responses": { "Unauthorized": { "description": "MISSING_API_KEY or INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "PLAN_NO_API_ACCESS; on send endpoints also PLAN_EXPIRED or MESSAGE_LIMIT_REACHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "RATE_LIMIT_EXCEEDED. Limits per API key per minute: sends 300, other writes 120, reads 300. See the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "details": { "description": "Extra context, such as the failing field or the provider's error." } } } } }, "Message": { "type": "object", "properties": { "message_id": { "type": "string" }, "provider_message_id": { "type": [ "string", "null" ], "description": "Id assigned by the channel, e.g. a WhatsApp wamid." }, "account_id": { "type": "string" }, "channel": { "type": "string", "description": "Internal channel code, e.g. fb_whatsapp, instagram." }, "contact_id": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "status": { "type": "string", "description": "sent, delivered, read or failed." }, "error": { "description": "Provider error when status is failed, else null." }, "sent_at": { "type": "string", "format": "date-time" } } }, "SendMessageRequest": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "description": "Channel account id from GET /channels/accounts/." }, "contact_id": { "type": "string", "description": "ChatMaxima contact id. Send one of contact_id, contact_ref_id or to." }, "contact_ref_id": { "type": "string", "description": "Your own contact id (contact_vendor_ref_id)." }, "to": { "type": "string", "description": "Phone number (WhatsApp Cloud API, SMS) or email address (email channels)." }, "text": { "type": "string", "description": "Message text, up to 4096 characters. Required unless media_url is set; always required on email.", "maxLength": 4096 }, "media_url": { "type": "string", "description": "https URL. On channels other than WhatsApp Cloud API it must come from POST /media/.", "format": "uri" }, "media_type": { "type": "string", "enum": [ "image", "video", "audio", "file" ] }, "file_name": { "type": "string" }, "subject": { "type": "string", "description": "Email subject; required on email channels.", "maxLength": 250 }, "conversation_id": { "type": "string", "description": "Web chat only.", "maxLength": 100 }, "reply_to": { "type": "string", "description": "Id of a customer message to answer, e.g. data.message_id from a reply webhook event. Quoted on WhatsApp Cloud API and Messenger; linked in the Inbox on other channels." }, "message_ref_id": { "type": "string", "description": "Idempotency key kept for 24 hours, up to 100 bytes." } } }, "Contact": { "type": "object", "properties": { "contact_id": { "type": "string" }, "contact_vendor_ref_id": { "type": "string" }, "contact_name": { "type": "string" }, "contact_email": { "type": "string" }, "contact_mobile": { "type": "string" }, "contact_location": { "type": "string" }, "contact_organization": { "type": "string" }, "contact_bio": { "type": "string" }, "contact_image_url": { "type": "string" }, "contact_attributes": { "type": "object", "additionalProperties": true }, "contact_created_at": { "type": "string" }, "contact_updated_at": { "type": "string" } } }, "ContactInput": { "type": "object", "description": "Send at least one of contact_vendor_ref_id, contact_mobile (or contact_phone) and contact_email.", "properties": { "contact_vendor_ref_id": { "type": "string" }, "contact_name": { "type": "string" }, "contact_email": { "type": "string" }, "contact_mobile": { "type": "string" }, "contact_phone": { "type": "string", "description": "Alias of contact_mobile." }, "contact_location": { "type": "string" }, "contact_organization": { "type": "string" }, "contact_bio": { "type": "string" }, "contact_image_url": { "type": "string" }, "contact_attributes": { "type": "object", "additionalProperties": true, "description": "Unknown keys create new workspace attributes; empty values are ignored." } } }, "Webhook": { "type": "object", "properties": { "webhook_id": { "type": "string" }, "callback_url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "account_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_datetime": { "type": "string" } } }, "WebhookEvent": { "type": "object", "description": "Body POSTed to your callback_url. Header X-CM-Signature is sha256= plus the HMAC-SHA256 of the raw body keyed with the webhook secret.", "properties": { "id": { "type": "string", "description": "Event id, the same across retries." }, "event": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.reply", "webhook.test" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } } } }, "paths": { "/channels/accounts/": { "get": { "tags": [ "Channel Accounts" ], "operationId": "listChannelAccounts", "summary": "List connected channel accounts", "parameters": [ { "name": "platform", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated: WhatsApp, Instagram, Facebook, Telegram, SMS, Email, Ticket, Web, GoHighLevel, WhatsApp Voice, Twilio Voice, Exotel." } ], "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "platform_name": { "type": "string" }, "account_identifier": { "type": [ "string", "null" ] }, "account_status": { "type": "string", "enum": [ "active", "pending" ] }, "account_created_datetime": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages/send/": { "post": { "tags": [ "Messages" ], "operationId": "sendMessage", "summary": "Send a message on any channel", "description": "Sends on WhatsApp, Instagram, Facebook Messenger, Telegram, SMS, email, tickets, web chat or GoHighLevel. WhatsApp, Instagram and Messenger enforce the 24-hour window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "example": { "account_id": "a1b2c3d4e5f6", "contact_id": "ct_abc123", "text": "Your order #1001 has shipped.", "message_ref_id": "order-1001-shipped" } } } }, "responses": { "201": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "properties": { "message_ref_id": { "type": [ "string", "null" ] }, "duplicate": { "type": "boolean" } } } ] } } } } } }, "400": { "description": "INVALID_JSON, MISSING_REQUIRED_FIELDS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND, CONTACT_NOT_ON_CHANNEL, UNKNOWN_CONVERSATION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "SEND_IN_PROGRESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "CHANNEL_NOT_SUPPORTED, ACCOUNT_INACTIVE, VALIDATION_ERROR, MEDIA_URL_NOT_ALLOWED, OUTSIDE_MESSAGING_WINDOW, SEND_REJECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SEND_UNCONFIRMED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages/{message_id}/": { "get": { "tags": [ "Messages" ], "operationId": "getMessage", "summary": "Get a message's delivery status", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Message" } } } } } }, "404": { "description": "MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/media/": { "post": { "tags": [ "Media" ], "operationId": "uploadMedia", "summary": "Upload a file to attach to messages", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "description": "Under 10 MB. Images, video, audio and common documents.", "format": "binary" } } } } } }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "media_url": { "type": "string", "format": "uri" }, "media_type": { "type": "string" }, "file_name": { "type": "string" } } } } } } } }, "400": { "description": "MISSING_FILE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "MEDIA_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "MEDIA_TYPE_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "UPLOAD_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/templates/": { "get": { "tags": [ "WhatsApp Templates" ], "operationId": "listWhatsappTemplates", "summary": "List WhatsApp templates", "parameters": [ { "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "name": "template", "in": "query", "schema": { "type": "string" }, "description": "A template_id." } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "template_id": { "type": "string" }, "template_name": { "type": "string" }, "language": { "type": "string" }, "language_name": { "type": "string" }, "template_type": { "type": "string" }, "template_status": { "type": "string" }, "account_id": { "type": "string" }, "variables": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "string" } }, "body_named": { "type": "boolean" }, "header_media": { "type": "boolean" }, "header_media_type": { "type": [ "string", "null" ] }, "header_text": { "type": "boolean" }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "sub_type": { "type": "string" }, "label": { "type": "string" } } } } } } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/templates/send/": { "post": { "tags": [ "WhatsApp Templates" ], "operationId": "sendWhatsappTemplate", "summary": "Send an approved WhatsApp template", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_no", "template" ], "properties": { "mobile_no": { "type": "string" }, "account_id": { "type": "string" }, "reference_id": { "type": "string" }, "broadcast_name": { "type": "string" }, "template": { "type": "object", "required": [ "template_name" ], "additionalProperties": { "type": "string" }, "description": "template_name plus body_1..N or named variables, header_text, header_media, header_media_filename, button_url_N, copy_code.", "properties": { "template_name": { "type": "string" } } } } }, "example": { "account_id": "a1b2c3d4e5f6", "mobile_no": "+15550001111", "reference_id": "order-1001", "template": { "template_name": "order_update", "body_1": "Jane", "body_2": "#1001" } } } } }, "responses": { "201": { "description": "Template message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "mobile_no": { "type": "string" }, "account_id": { "type": "string" }, "template_name": { "type": "string" }, "broadcast_name": { "type": [ "string", "null" ] }, "reference_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_datetime": { "type": "string" } } } } } } } }, "404": { "description": "TEMPLATE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CONTACT_NUMBER_CHANGED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "MISSING_MOBILE_NO, INVALID_MOBILE_NO, ACCOUNT_RESOLUTION_FAILED, WHATSAPP_SEND_REJECTED and request-specific validation codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SEND_UNCONFIRMED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/messages/send/": { "post": { "tags": [ "WhatsApp Messages" ], "operationId": "sendWhatsappMessage", "summary": "Send a free-form WhatsApp message inside the 24-hour window", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_no", "message" ], "properties": { "mobile_no": { "type": "string" }, "account_id": { "type": "string" }, "reference_id": { "type": "string", "description": "Required for status and reply webhooks." }, "message": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "document", "video", "audio" ] }, "text": { "type": "string" }, "caption": { "type": "string" }, "media_url": { "type": "string", "format": "uri" }, "file_name": { "type": "string" } } } ] } } }, "example": { "mobile_no": "+15550001111", "reference_id": "ticket-2042", "message": "Your refund has been approved." } } } }, "responses": { "201": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "mobile_no": { "type": "string" }, "account_id": { "type": "string" }, "reference_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_datetime": { "type": "string" } } } } } } } }, "422": { "description": "MISSING_MOBILE_NO, INVALID_MOBILE_NO, UNSUPPORTED_MESSAGE_TYPE, MISSING_MESSAGE, MISSING_MEDIA_URL, INVALID_MEDIA_URL, ACCOUNT_RESOLUTION_FAILED, WINDOW_CLOSED, WHATSAPP_SEND_REJECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SEND_UNCONFIRMED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/messages/{message_id}/status/": { "get": { "tags": [ "WhatsApp Messages" ], "operationId": "getWhatsappMessageStatus", "summary": "Get a WhatsApp message status by wamid", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The wamid, URL-encoded." } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "delivered", "read", "failed" ] }, "error": {}, "created_datetime": { "type": "string" }, "updated_datetime": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "MISSING_MESSAGE_ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/webhooks/": { "get": { "tags": [ "WhatsApp Webhooks" ], "operationId": "listWhatsappWebhooks", "summary": "List webhook subscriptions", "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "WhatsApp Webhooks" ], "operationId": "createWhatsappWebhook", "summary": "Create a webhook subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "callback_url", "events" ], "properties": { "callback_url": { "type": "string", "description": "Public HTTPS URL.", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "read", "failed", "reply" ] } }, "account_id": { "type": "string" } } }, "example": { "callback_url": "https://example.com/hooks/chatmaxima", "events": [ "delivered", "read", "failed", "reply" ] } } } }, "responses": { "201": { "description": "Webhook created; the secret is shown only once", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] } } } } } }, "422": { "description": "MISSING_CALLBACK_URL, INVALID_CALLBACK_URL, MISSING_EVENTS, INVALID_EVENT, INVALID_ACCOUNT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "callbacks": { "event": { "{$request.body#/callback_url}": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the event. Failures are retried after 1 min, 5 min, 30 min and 2 h." } } } } } } } }, "/whatsapp/webhooks/{webhook_id}/": { "delete": { "tags": [ "WhatsApp Webhooks" ], "operationId": "deleteWhatsappWebhook", "summary": "Deactivate a webhook subscription", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deactivated" }, "400": { "description": "MISSING_WEBHOOK_ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/whatsapp/webhooks/{webhook_id}/test/": { "post": { "tags": [ "WhatsApp Webhooks" ], "operationId": "testWhatsappWebhook", "summary": "Send a signed test event", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "http_status": { "type": "integer" }, "response": { "type": "string" } } } } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "contact_vendor_ref_id", "in": "query", "schema": { "type": "string" } }, { "name": "contact_mobile", "in": "query", "schema": { "type": "string" } }, { "name": "contact_email", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "operationId": "upsertContact", "summary": "Create or update a contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" }, "example": { "contact_vendor_ref_id": "crm-001", "contact_name": "Jane Doe", "contact_mobile": "+15551234567" } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "201": { "description": "Contact created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "description": "INVALID_JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "INVALID_CONTACT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/sync/": { "post": { "tags": [ "Contacts" ], "operationId": "syncContacts", "summary": "Create or update up to 500 contacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/ContactInput" } } } } } } }, "responses": { "200": { "description": "Sync completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "total": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "updated", "failed" ] }, "contact_id": { "type": "string" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "description": "MISSING_CONTACTS_ARRAY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "BATCH_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}/": { "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Get a contact by contact_id or contact_vendor_ref_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact (only the fields sent)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "MOBILE_LOCKED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/export/": { "get": { "tags": [ "Conversations" ], "operationId": "exportConversations", "summary": "Export conversation history as flat rows", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 or YYYY-MM-DD HH:MM:SS. Defaults to the start of the current UTC day." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Same format as from. Defaults to the end of the current UTC day." } ], "responses": { "200": { "description": "Conversation export", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "conversation_alias": { "type": "string" }, "contact_name": { "type": "string" }, "contact_mobile": { "type": "string" }, "contact_email": { "type": "string" }, "direction": { "type": "string" }, "message_type": { "type": "string" }, "message_text": { "type": "string" }, "media_url": { "type": "string" }, "agent_name": { "type": "string" }, "message_datetime": { "type": "string" }, "status": { "type": "string" }, "department": { "type": "string" }, "labels": { "type": "string" }, "message_id": { "type": "integer" }, "lead_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }