Home/HighLevel/Features/Developer Resources/Add inbound messages to HighLevel conversations using a contact ID

Agency, Settings and Integrations

Add inbound messages to HighLevel conversations using a contact ID

In short

The Add Inbound Message endpoint lets you send an inbound message directly into the proper conversation by providing a Contact ID. The platform decides whether to append to an existing thread or start a new one, reducing API calls and simplifying integration logic.

AreaDeveloper Resources · Developer Resources
Used forSaaS startup handling SMS lead notifications, Healthcare clinic importing patient email replies, Ecommerce store backfilling WhatsApp order updates
Setup steps5 steps in 1 task
Last updatedNovember 17, 2026

01Who this is for

  • Developers building messaging integrations need a simple way to ingest provider messages without extra lookup steps.
  • Support teams using the platform benefit from messages appearing in the correct thread automatically, improving agent context.
  • Product managers who want to backfill historical inbound messages can do so with metadata timestamps.

02Add inbound messages, explained

The endpoint accepts a Contact ID, channel, optional endpoint details, message content, and metadata. When the request is processed, HighLevel checks for an open conversation on the same channel. If one exists, the message is added to that thread; otherwise a new conversation is created and its ID returned in the response. This logic works for SMS, WhatsApp, Email, Messenger, Instagram, and Web Chat channels.

The feature lives under the Conversations API group. Calls are made to the POST /conversations/inbound messages path with a bearer token that has the Conversations and Contacts scopes. The response includes identifiers such as messageId and conversationId, confirming where the inbound message landed.

Including an idempotencyKey prevents duplicate records if a request is retried after a timeout. The system respects rate limit headers and returns standard HTTP error codes for invalid data, authentication problems, or payload size violations.

03How businesses use add inbound messages

  • SaaS startup handling SMS lead notifications. The startup posts inbound SMS messages directly using the lead's contactId. The platform appends the message to any open SMS thread or creates a new conversation, keeping the sales pipeline tidy.
  • Healthcare clinic importing patient email replies. The clinic's integration reads email replies, supplies the patient’s contactId, email channel, and message body. HighLevel adds the inbound email to the right patient record without extra conversation lookups.
  • Ecommerce store backfilling WhatsApp order updates. The store sends historical WhatsApp messages with a timestamp in metadata. HighLevel inserts each inbound into the appropriate thread, preserving the chronological order in the timeline.

04The numbers and rules that matter

  • Supported channels: SMS, WhatsApp, email, messenger, Instagram, webchat.
  • Attachments include type, URL, filename, sizeBytes.

05Before you start

  • Obtain API access with Conversations and Contacts scopes for the required role.
  • Authenticate using OAuth or an API key as defined by your environment.
  • Ensure you have a valid Contact ID for the target contact.
  • Set the correct location or workspace context if the contact exists in multiple locations.

06How to set up and use add inbound messages in HighLevel

Add inbound message (Contact Based)

  1. Generate an access token that includes the Conversations and Contacts scopes.
  2. Collect the Contact ID, channel, optional endpoint information, message content, and any metadata needed.
  3. Build the JSON payload matching the required fields, including a unique idempotencyKey.
  4. Send a POST request to /conversations/inbound messages with the Authorization header and the JSON body.
  5. Read the response to obtain the messageId and conversationId, confirming the inbound was recorded.

07What it looks like in HighLevel

08Settings that matter

  • contactId. Identifies the contact whose conversation will receive the inbound message.
  • channel. Specifies the messaging medium such as sms, whatsapp, email, messenger, instagram, or webchat.
  • endpoint. Provides a phone number or email address to disambiguate when a contact has multiple addresses for the same channel.
  • content. Contains the text of the message and optional attachments like images, files, or videos.
  • metadata. Allows you to pass providerMessageId, externalThreadKey, and a timestamp for ordering or correlation.
  • idempotencyKey. A unique token that ensures retries do not create duplicate messages.

09Things to know before you rely on it

  • Attachment size is limited per channel; oversized files trigger a 413 Payload Too Large response.
  • Rate limits apply; a 429 response means you must back off according to the Retry After header.
  • If a contact has only closed or archived threads on the channel, a new conversation is created.
  • The endpoint is backward compatible; existing Conversation ID based calls continue to work.

10If something goes wrong

  • 400 Bad Request, missing or invalid fields. Check that contactId, channel, and content are present and correctly formatted.
  • 401 or 403, authentication failed or insufficient scope. Verify the bearer token includes the required Conversations and Contacts scopes.
  • 404 Not Found, contactId not found. Ensure the Contact ID is valid in the location context used for the call.
  • 409 Conflict, idempotency key collision. Use a truly unique idempotencyKey for each distinct inbound message.
  • 413 Payload Too Large, attachment exceeds limits. Reduce attachment size or use a supported media type within channel limits.
  • 429 Too Many Requests, rate limit exceeded. Implement exponential backoff and respect the Retry After header.
  • 5xx, transient server error. Retry the request with the same idempotencyKey after a brief delay.

11How it connects to the rest of HighLevel

Michael's take

Michael Reimer
Michael ReimerFounder of CRM Pros, HighLevel Commander and Certified Admin

Add inbound messages is a practical shortcut for anyone feeding messages into HighLevel.

Teams that already have a stable conversation lookup flow and don’t need the extra speed can skip it.

Get More InformationOpens on HighLevelPublished November 2, 2026 · Updated November 17, 2026

Common questions

Common questions about add inbound messages.

Can I still post inbound messages using a Conversation ID?

Yes. Existing flows that rely on a Conversation ID remain supported while the contact based endpoint provides a shortcut.

What happens if I omit the channel field?

The request is rejected with a 400 error; the channel is required to route the message.

How does the system choose a conversation when multiple threads exist?

It prefers an open thread on the same channel. If none exists, it creates a new conversation.

How do I prevent duplicate messages when retrying after a timeout?

Include an idempotencyKey with each request and reuse the same key for retries.

Can I backfill historical inbound messages?

Yes. Provide a metadata.timestamp reflecting the original time and the message will be placed accordingly in the timeline.

How do I target the correct location when a contact exists in multiple workspaces?

Use credentials or headers that are scoped to the desired location; the API call will act on that workspace.

Next step

Pick the features that matter. Then get the plan that unlocks them.

Explore the features you want, start with the five at the top, and upgrade through my link when you are ready. The bonuses and the team come with it.

The features directory explains every HighLevel feature in plain English. Browse it to see what the platform can do.

Back to the FeaturesSee the full details
⌃

Site preview

Explore the next page

This destination is reserved in the page inventory and is not built yet.