Skip to main content
GHL MCP Guide
CVS

Conversation CRUD

Conversations & Messaging · Intermediate · Updated March 2026

Create, retrieve, update, and delete conversations across all channels. Search the unified inbox including SMS, email, Facebook, Instagram, WhatsApp, and live chat.

Every interaction with a contact — SMS, email, Facebook Messenger, Instagram DM, WhatsApp, live chat — lives inside a conversation. Conversations are the unified threads that tie all communication into a single timeline per contact. Managing conversations through MCP gives you programmatic access to the entire communication history and lets you create, search, and organize these threads from external systems.

What This MCP Tool Does

Full CRUD operations on conversation records. Search across all conversations with advanced filters, retrieve individual conversations with their message history, create new conversations, update conversation properties (status, assignee, tags), and delete conversations. This is the central hub for all messaging activity in GHL.

Endpoint Reference

Search conversations: GET /conversations/search Search across all channels with filters for status, assignee, contact, date range, and unread status. Supports pagination for large result sets.

Get a conversation: GET /conversations/{conversationId} Retrieve a single conversation with its metadata, contact association, and message history.

Create a conversation: POST /conversations Start a new conversation with a contact. Useful for initiating communication threads from external triggers.

Update a conversation: PUT /conversations/{conversationId} Change conversation properties like status (open/closed), assigned team member, or conversation-level tags.

Delete a conversation: DELETE /conversations/{conversationId} Remove a conversation record. Messages within the conversation are also removed.

Authentication

Requires a Private Integration Token (PIT) with the conversations scope enabled.

Key Parameters

For search:

  • contactId — filter by specific contact
  • assignedTo — filter by assigned team member
  • status — open, closed, or all
  • query — text search across messages
  • sort — ordering (typically by last message date)
  • limit, offset — pagination

For create/update:

  • contactId — the contact this conversation belongs to
  • assignedTo — team member user ID
  • status — open or closed

Important Notes

Conversations are multi-channel. A single contact might have SMS conversations, email threads, and Facebook Messenger chats, each as separate conversation records. The search endpoint returns all of them unless you filter by channel type.

Closing a conversation via MCP updates its status in the inbox. Reopening happens automatically when a new inbound message arrives from the contact on that channel.

Deleting a conversation is permanent and removes all messages within it. There’s no undo. Use status changes (open/close) instead of deletion for inbox management.

The search endpoint is powerful but can be slow on locations with very high message volume. Use specific filters (contact ID, date range, assignee) to narrow results rather than searching broadly.

Common Questions

Can I search for conversations by message content? Yes. The query parameter searches across message text within conversations.

How do I find all unread conversations? Filter by status and check the unread message count in the response. The search endpoint supports filtering for conversations with unread messages.

Can I assign a conversation to a team member via MCP? Yes. Use the update endpoint with the assignedTo parameter set to the team member’s user ID.

Do conversations get created automatically when I send a message? Yes. If no existing conversation exists for the contact on that channel, sending a message via SMS Operations or Email Send creates a conversation automatically.

Back to GHL MCP Guide