Welcome to CRM Messaging API! To enqueue a message, send a POST request to the endpoint: POST /enqueue ============================================== SECTION 1: SMS MESSAGING ============================================== SMS Message Example: { "channel": "sms", // Specify SMS channel "to": "+1234567890", // Recipient's phone number "msg": "Your message here", // Message content "type": "conversational", // Message type (conversational/bulk/automation) "from": "+0987654321", // Sender's phone number "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "account_sid": "your_sid", // Your account SID "auth_token": "your_token", // Your auth token "msgServiceId": "your_service_id" // Optional: Messaging Service ID }, "mediaUrl": "https://example.com/image.jpg", // Optional: Media URL for MMS "shortenUrls": true // Optional: URL shortening } SMS Notes: - All phone numbers must include country code - Maximum message length: 1600 characters - Supported media types for MMS: images, videos, PDFs - Messaging Service ID can replace "from" number - Authentication via JWT token or account_sid/auth_token - Status callbacks include message delivery status - Supports both single and multiple media URLs ============================================== SECTION 2: WHATSAPP MESSAGING ============================================== 1. Text Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "msg": "Hello! This is a text message", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 2. Media Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "mediaType": "image", // Options: image, video, document, audio "mediaUrl": "https://example.com/media.jpg", "caption": "Optional caption", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 3. Template Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "template": "order_update", "language": "en", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/product.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "12345" } ] } ], "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 4. Interactive Button Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "interactive": { "type": "button", "body": { "text": "Please select an option" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "button1", "title": "Yes" } }, { "type": "reply", "reply": { "id": "button2", "title": "No" } } ] } }, "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 5. List Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "interactive": { "type": "list", "header": { "type": "text", "text": "Available Options" }, "body": { "text": "Please select from the list" }, "action": { "button": "Select an option", "sections": [ { "title": "Section 1", "rows": [ { "id": "option1", "title": "Option 1", "description": "Description 1" } ] } ] } }, "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 6. Location Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "latitude": "37.422", "longitude": "-122.084", "name": "Location Name", "address": "123 Street Name", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 7. Contacts Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "contacts": [ { "name": { "first_name": "John", "last_name": "Doe" }, "phones": [ { "phone": "+1234567890", "type": "CELL" } ] } ], "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 8. Reaction Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "messageId": "wamid.xxx...", "emoji": "👍", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 9. Reply Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "msg": "This is a reply", "quotedMessageId": "wamid.xxx...", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 10. Sticker Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "stickerUrl": "https://example.com/sticker.webp", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 11. Carousel Template: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "carousel": { "template_name": "your_carousel_template", "language": "en", "cards": [ { "index": 0, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/product1.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Product 1" }, { "type": "text", "text": "$99.99" } ] } ] } ] }, "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 12. Single Product Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "msg": "Check out this product!", "catalogId": "your_catalog_id", "productRetailerId": "your_product_id", "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } 13. Multi-Product Catalog Message: { "channel": "whatsapp", "to": "+1234567890", "type": "conversational", "catalogId": "your_catalog_id", "interactive": { "type": "product_list", "header": { "type": "text", "text": "Our Products" }, "body": "Check out our products", "sections": [ { "title": "Featured Products", "product_items": [ { "product_retailer_id": "product_1" } ] } ] }, "clientMessageId": "your-unique-id-123", // Optional: Your message tracking ID "StatusCallback": "https://your-domain.com/callback", // Optional: Status callback URL "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" } } ============================================== CALLBACK NOTIFICATIONS ============================================== If you provide a StatusCallback URL, you will receive POST requests with the following payloads: Success Callback: { "messageId": "your-unique-id-123", // Your provided clientMessageId "providerMessageId": "provider-msg-id", // Provider's message ID (e.g., Twilio SID or WhatsApp ID) "channel": "sms/whatsapp", // Channel used "status": "sent", // Message status "timestamp": "2024-01-24T12:34:56.789Z", // ISO timestamp "to": "+1234567890", // Recipient "from": "+0987654321", // Sender "provider_response": { // Complete provider response // Provider-specific response details } } Error Callback: { "messageId": "your-unique-id-123", // Your provided clientMessageId "channel": "sms/whatsapp", // Channel used "status": "failed", // Error status "error": "Detailed error message", // Error description "timestamp": "2024-01-24T12:34:56.789Z", // ISO timestamp "to": "+1234567890", // Recipient "from": "+0987654321" // Sender } Callback Notes: - Callback URL must be publicly accessible - Callbacks are sent asynchronously - Multiple callbacks may be sent for the same message - Recommended to implement idempotency in your callback handler - Callback timeout: 10 seconds - Failed callbacks are not retried ============================================== GENERAL NOTES ============================================== Message Types: - conversational: For 1:1 customer service messages - bulk: For marketing/promotional broadcasts - automation: For automated notifications Media Size Limits: - Image: 5MB (JPEG, PNG) - Video: 16MB - Document: 100MB - Audio: 16MB - Sticker: 100KB (WebP format) Queue Configuration: - Conversational: 1 message per batch, 0s timeout - Bulk: 100 messages per batch, 10s timeout - Automation: 20 messages per batch, 10s timeout - Retry attempts: 3 for all queues - Dead letter queues enabled for failed messages Additional Notes: - All phone numbers must include country code - Media files must be publicly accessible via HTTPS - Templates must be pre-approved - Interactive messages support up to 10 buttons - List messages support up to 10 sections - Carousel templates support up to 10 cards - Product catalogs must be pre-configured Response Format: { "success": true, "message": "Message enqueued successfully!", "messageId": "your-unique-id-123" // Use this ID to track your message } Error Response: { "error": "Error description", "details": "Detailed error message" } ============================================== STATUS CALLBACKS ============================================== Your StatusCallback URL will receive POST requests with the following information: SMS Status Callback: { "messageId": "your-unique-id-123", "providerMessageId": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "channel": "sms", "status": "delivered/failed/sent", "timestamp": "2024-01-24T12:34:56.789Z", "to": "+1234567890", "from": "+0987654321", "provider_response": { "account_sid": "ACxxxxx", "api_version": "2010-04-01", "body": "Your message here", "date_created": "Thu, 24 Jan 2024 12:34:56 +0000", "date_sent": "Thu, 24 Jan 2024 12:34:57 +0000", "direction": "outbound-api", "error_code": null, "error_message": null, "from": "+0987654321", "messaging_service_sid": "MGxxxxx", "num_media": "0", "num_segments": "1", "price": null, "price_unit": null, "sid": "SMxxxxx", "status": "delivered", "to": "+1234567890", "uri": "/2010-04-01/Accounts/ACxxxxx/Messages/SMxxxxx.json" } } WhatsApp Status Callback: { "messageId": "your-unique-id-123", "providerMessageId": "wamid.xxx...", "channel": "whatsapp", "status": "sent/delivered/read/failed", "timestamp": "2024-01-24T12:34:56.789Z", "to": "+1234567890", "from": "your_phone_number_id", "provider_response": { // Complete WhatsApp response } } Thank you for using the CRM Messaging API! ============================================== BULK MESSAGE ENDPOINTS ============================================== 1. Bulk SMS API: POST /bulk/sms Request Body: { "clientBatchId": "batch123", // Optional: Your batch tracking ID "StatusCallback": "https://your-domain.com/callback", "credentials": { "account_sid": "your_sid", "auth_token": "your_token", "msgServiceId": "your_service_id" }, "messages": [ // Array of messages to send { "to": "+1234567890", "msg": "Message 1", "mediaUrl": "https://example.com/image1.jpg" }, { "to": "+0987654321", "msg": "Message 2" } ] } 2. Bulk WhatsApp API: POST /bulk/whatsapp Request Body: { "clientBatchId": "batch456", // Optional: Your batch tracking ID "StatusCallback": "https://your-domain.com/callback", "credentials": { "accessToken": "your_access_token", "phoneNumberId": "your_phone_number_id" }, "messages": [ // Array of messages to send { "to": "+1234567890", "template": "order_update", "language": "en", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "12345" } ] } ] }, { "to": "+0987654321", "msg": "Hello World" } ] } Bulk Message Response Format: { "success": true, "message": "Bulk messages enqueued successfully", "batchId": "batch123", "totalMessages": 100 } Bulk Status Callback Format: { "batchId": "batch123", "messageId": "batch123-0", "providerMessageId": "SMxxxxx/wamid.xxx", "channel": "sms/whatsapp", "status": "sent", "timestamp": "2024-01-24T12:34:56.789Z", "to": "+1234567890", "from": "+0987654321/phoneNumberId", "messageIndex": 0, "totalMessages": 100, "provider_response": { // Provider-specific details } } Rate Limits: - SMS: 30 messages per second - WhatsApp: 80 messages per second