Send SMS and MMS messages to contacts, manage two-way text conversations, and schedule or cancel outbound messages through the GHL MCP server. This tool uses POST /conversations/messages with the type set to SMS, giving you full control over text communication from external scripts and automations.
Prerequisites
Before making your first SMS call, confirm the following:
- A GoHighLevel sub-account with an active phone number configured for SMS
- The phone number must be A2P 10DLC registered (unregistered numbers get filtered by carriers)
- A Private Integration Token (PIT) with the
conversationsscope enabled - The contact ID of the recipient you want to message
- For MMS, publicly accessible URLs for any media attachments
If you do not have a phone number yet, navigate to Settings > Phone Numbers in GHL and purchase one before proceeding.
Set Up Authentication
Generate a PIT from your GHL sub-account under Settings > Integrations > Private Integrations. Click Create New, give it a name like “MCP SMS Bot,” and enable the conversations scope. Copy the token and store it securely.
Configure your MCP client with the token. Every request must include the header Authorization: Bearer YOUR_PIT_TOKEN along with Content-Type: application/json and the Version: 2021-07-28 header.
Make Your First Call
Send a basic SMS using POST /conversations/messages with the following body:
type— set to"SMS"contactId— the recipient contact’s GHL IDmessage— your text content (1,600 character limit per segment)conversationProviderId— the phone number ID to send from
For MMS messages, add an attachments array with publicly accessible image or media URLs. Supported formats include JPEG, PNG, and GIF. You can also include a conversationId to send within an existing thread, keeping the conversation history grouped.
To schedule a message, include scheduling parameters in the same request body with a future timestamp. Cancel a scheduled message before delivery using the cancel endpoint with the message ID.
Handle the Response
A successful call returns a JSON object with the message ID, delivery status, and conversation thread details. Store the messageId for tracking delivery and any follow-up operations.
Check the status field. A value of "sent" confirms the message was dispatched to the carrier. If the status shows "failed", inspect the errorMessage field for details. Common issues include invalid phone numbers, DND-blocked contacts, and unregistered sending numbers.
Messages sent through MCP appear in the contact’s conversation timeline alongside UI-sent and workflow-sent messages. Inbound replies from contacts trigger standard GHL workflows and show up in the conversations inbox.
Test Your Setup
Run a test by sending an SMS to your own phone number or a test contact. Verify the following:
- The message arrives on the recipient’s device
- The message appears in Conversations in the GHL dashboard
- The
conversationProviderIdmatches your intended sending number - If sending MMS, confirm the media attachment renders correctly
- Check DND status via Contact CRUD before sending to avoid blocked messages
Send a second message to the same contact and confirm it threads into the same conversation. This validates that conversation grouping works correctly.
For production use, implement rate limiting and error handling to manage carrier delivery limits and failed sends gracefully. See the full SMS Operations guide for advanced patterns, and explore Message Manager for retrieving and updating message records after delivery.