Help Center

Introduction

The Add Inbound Message API endpoint allows you to post inbound messages directly into your CRM's Conversations by providing a Contact ID. This method simplifies your integration by letting the system automatically find the correct conversation thread for the contact or create a new one, eliminating the need for you to first look up or create a Conversation ID.

Key Benefits

Using this contact-based approach offers several advantages for your integrations:

Reduced API Calls: You avoid the separate step of finding or creating a conversation before sending a message.
Simpler Logic: Your code doesn't need complex branching to handle cases where a conversation does or doesn't already exist.
Cleaner Inbox: Messages are guaranteed to land in the correct, unified conversation thread for the contact within the CRM.
Improved Resilience: Fewer API calls mean fewer potential points of failure in your message ingestion flow.

Endpoint and Request Format

To use this feature, send a POST request to the /conversations/inbound-messages endpoint. Your request must include an authorization header and use the application/json content type.

The request body should be a JSON object containing the following key fields:

contactId (Required): The unique ID of the contact receiving the message.
channel (Required): The communication channel, such as sms, whatsapp, email, messenger, instagram, or webchat.
endpoint (Optional but Recommended): An object specifying the contact's address for the given channel, like a phone number or email address. This helps the system disambiguate if a contact has multiple addresses.
content (Required): An object containing the message. This includes a text field for the message body and an optional attachments array for any media files.
metadata (Optional): An object for your own tracking data, such as a provider message ID or timestamp.
idempotencyKey (Recommended): A unique key you generate to prevent the same message from being created twice if a request is retried.

How Threading Works

The system uses intelligent rules to decide where to place your message:

If the contact has an open, active conversation on the exact same channel, the new inbound message will be appended to that existing thread.
If no suitable open conversation is found (e.g., the contact has no conversations on that channel, or only archived/closed ones), the system will create a new conversation automatically.
The conversationId for the thread used (either existing or new) is returned in the API response.

Setup and Requirements

Before you begin, ensure you have the following:

API Access: Valid authentication credentials (like an OAuth token or API key) with the necessary permissions for Conversations and Contacts.
Contact ID: A reliable method to obtain the correct Contact ID for your message, typically by matching on a phone number or email address from your upstream system.
Location Context: Your API call must be made in the context of the correct location or workspace that owns the contact data.

Channel-Specific Notes

Different channels have different capabilities and limitations:

SMS/MMS: Be mindful of character limits for text and file size/type restrictions for media attachments.
WhatsApp: Adhere to platform-specific rules for message templates and media specifications.
Email: Supports text and HTML bodies, along with file attachments.
Messenger/Instagram: These social channels may have specific rate limits and media requirements.
Web Chat: Rich content support depends on your chat widget's configuration.

Handling Errors and Retries

For robust integrations, implement proper error handling:

Always include an idempotencyKey in your request. If you retry a failed request with the same key, the system will not create a duplicate message.
Implement a retry policy with exponential backoff for server errors (5xx status codes) or timeouts.
If you receive a 429 Too Many Requests response, respect the Retry-After header if provided.
Common error responses include 400 Bad Request for invalid data, 401/403 for authentication issues, and 404 Not Found if the provided Contact ID cannot be located.