Conversation CRUD Setup

Create, read, update, and delete conversation threads across every messaging channel in GoHighLevel. This tool covers SMS, email, Facebook Messenger, Instagram DM, WhatsApp, Google Business Chat, and live chat. Use it to search conversations, retrieve thread details, and manage conversation records programmatically.

Prerequisites

Before working with conversation endpoints, confirm the following:

• A GoHighLevel sub-account with at least one messaging channel configured (phone number, email, or social integration)
• A Private Integration Token (PIT) with the conversations scope enabled
• At least one existing contact to associate conversations with
• Familiarity with your location ID (found in Settings > Business Info)

Conversations are the container objects that hold messages. Each conversation links to a contact and a specific channel, so you need both a contact record and an active channel before creating threads.

Set Up Authentication

Generate a PIT from Settings > Integrations > Private Integrations in your sub-account. Click Create New, name it “MCP Conversation Manager,” and enable the conversations scope. Copy the token and store it in your MCP client’s environment configuration.

Every API request requires three headers: Authorization: Bearer YOUR_PIT_TOKEN, Content-Type: application/json, and Version: 2021-07-28. These headers apply to all CRUD operations on conversations.

Make Your First Call

Start by searching for existing conversations with GET /conversations/search. Pass your locationId as a required parameter. Optional filters include:

• contactId — filter to a specific contact’s conversations
• assignedTo — filter by assigned team member
• status — filter by "open", "closed", or "all"
• query — search by keyword across message content

To get a single conversation, call GET /conversations/{id} with the conversation ID. This returns the full thread metadata including the channel type, assigned user, and message count.

To create a new conversation, use POST /conversations with a body containing the locationId and contactId. You can also specify the channel type and initial assignment.

To update a conversation, call PUT /conversations/{id} with fields like assignedTo, status, or starred. To delete, use DELETE /conversations/{id} to remove the conversation record entirely.

Handle the Response

Search results return a paginated array of conversation objects. Each object includes the id, contactId, type (channel), lastMessageDate, unreadCount, and assignment details. Use the pagination fields startAfterDate and limit to page through large result sets.

Single conversation lookups return the same object structure with full metadata. Check the type field to determine the channel: values include SMS, Email, FB, IG, WhatsApp, GMB, and Live_Chat.

For create and update operations, the response returns the complete conversation object reflecting the changes. A 404 error on GET or DELETE means the conversation ID is invalid or already removed.

Test Your Setup

Run through each CRUD operation to validate your integration:

• Search: Call GET /conversations/search with your locationId and confirm you receive a list of conversations
• Read: Pick a conversation ID from the search results and call GET /conversations/{id} to retrieve its details
• Create: Create a new conversation with a test contact and verify it appears in the GHL inbox
• Update: Change the status to "closed" using PUT /conversations/{id} and confirm it updates in the UI
• Delete: Remove a test conversation and verify it no longer appears in search results

See the full Conversation CRUD guide for advanced filtering, pagination strategies, and channel-specific behavior. To send messages within conversations, use SMS Operations or Email Send.