GoHighLevel Conversations API

Send A New Message

POST/conversations/messages

POST /conversations/messages Post the necessary fields for the API to send a new message It takes 25 body fields, requires the conversations/message.write scope and authenticates with a sub-account (location) token.

Request and authentication

Method: POST
Full URL: https://services.leadconnectorhq.com/conversations/messages
Scopes: conversations/message.write
Token type: Sub-account (location) token
Accepted auth: OAuth Access Token, Private Integration Token
API version header: Version: 2021-07-28
Schema verified: 22 June 2026

Request body

JSON body fields. Nested objects are shown indented under their parent.

Name	Type	Description
`type`required	`string`	Type of message being sent One of: `SMS`, `RCS`, `Email`, `WhatsApp`, `IG`, `FB`, `Custom`, `Live_Chat`, `TIKTOK` Example: `Email`
`subType`required	`object`	Type of message being sent Example: `Email`
`contactId`required	`string`	ID of the contact receiving the message Example: `abc123def456`
`appointmentId`	`string`	ID of the associated appointment Example: `appt123`
`attachments`	`array`	Array of attachment URLs Example: `https://storage.com/file1.pdf,https://storage.com/file2.jpg`
`emailFrom`	`string`	Email address to send from Example: `sender@company.com`
`emailCc`	`array`	Array of CC email addresses Example: `cc1@company.com,cc2@company.com`
`emailBcc`	`array`	Array of BCC email addresses Example: `bcc1@company.com,bcc2@company.com`
`html`	`string`	HTML content of the message Example: `<p>Hello World</p>`
`message`	`string`	Text content of the message Example: `Hello, how can I help you today?`
`subject`	`string`	Subject line for email messages Example: `Important Update`
`replyMessageId`	`string`	ID of message being replied to Example: `msg123`
`templateId`	`string`	ID of message template Example: `template123`
`threadId`	`string`	ID of message thread. For email messages, this is the message ID that contains multiple email messages in the thread Example: `thread123`
`scheduledTimestamp`	`number`	UTC Timestamp (in seconds) at which the message should be scheduled Example: `1669287863`
`conversationProviderId`	`string`	ID of conversation provider Example: `provider123`
`emailTo`	`string`	Email address to send to, if different from contact's primary email. This should be a valid email address associated with the contact. Example: `recipient@company.com`
`customSubtypeId`	`string`	Custom subtype ID for email unsubscription preferences. Only applies to email messages. Example: `507f1f77bcf86cd799439011`
`emailReplyMode`	`string`	Mode for email replies One of: `reply`, `reply_all` Example: `reply_all`
`fromNumber`	`string`	Phone number used as the sender number for outbound messages Example: `+1499499299`
`toNumber`	`string`	Recipient phone number for outbound messages Example: `+1439499299`
`forward`	`unknown`	Forwarding configuration for emails Example: `[object Object]`
`status`required	`string`	Message status One of: `delivered`, `failed`, `pending`, `read` Example: `delivered`
`usesNativeSchedulingAi`	`boolean`	Whether the scheduled email uses native AI for the email scheduling Example: `false`
`optimizationPeriod`	`string`	Optimization period in hours (24h, 48h, or 72h) One of: `24h`, `48h`, `72h` Example: `24h`

Response fields

Top-level fields returned on a successful call.

Name	Type	Description
`conversationId`required	`string`	Conversation ID. Example: `ABC12h2F6uBrIkfXYazb`
`emailMessageId`	`string`	This contains the email message id (only for Email type). Use this ID to send inbound replies to GHL to create a threaded email. Example: `rnGyqh2F6uBrIkfhFo9A`
`messageId`required	`string`	This is the main Message ID Example: `t22c6DQcTDf3MjRhwf77`
`messageIds`	`array`	When sending via the GMB channel, we will be returning list of messageIds instead of single messageId.
`msg`	`string`	Additional response message when sending a workflow message Example: `Message queued successfully.`
`forwardData`	`unknown`	Optional metadata for forwarded email Example: `[object Object]`
`status`required	`string`	Message status One of: `delivered`, `failed`, `pending`, `read` Example: `delivered`

Example request

Copy-paste ready. Swap YOUR_TOKEN for your access token or Private Integration Token.

curl -X POST 'https://services.leadconnectorhq.com/conversations/messages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "Email",
    "subType": "Email",
    "contactId": "abc123def456",
    "status": "delivered"
  }'

Skip the schema lookup

Hylo gives your AI agent this schema — and the other 52 documented here — without you looking anything up. Ask in plain English; it picks the endpoint, fills the body, and can run the call against your own sub-account.

View pricing Read the setup guide

More conversations endpoints