Files

T

urieljareth a35d26fac0 Primer commit

2026-05-30 14:31:19 -06:00

111 KiB

Raw Blame History

GHL Conversations API

Endpoints: 29 Base URL: https://rest.gohighlevel.com/v1

Version Header(s): 2021-04-15

Endpoints

POST /conversations/ — Create Conversation
GET /conversations/locations/{locationId}/messages/{messageId}/transcription — Get transcription by Message ID
GET /conversations/locations/{locationId}/messages/{messageId}/transcription/download — Download transcription by Message ID
POST /conversations/messages — Send a new message
DELETE /conversations/messages/email/{emailMessageId}/schedule — Cancel a scheduled email message.
GET /conversations/messages/email/{id} — Get email by Id
GET /conversations/messages/export — Export messages by location ID
POST /conversations/messages/inbound — Add an inbound message
POST /conversations/messages/outbound — Add an external outbound call
POST /conversations/messages/review-reply — Send a review reply to Google My Business
POST /conversations/messages/upload — Upload file attachments
POST /conversations/messages/upload/complete — Complete file upload
POST /conversations/messages/upload/initiate — Initiate file upload to GCS
GET /conversations/messages/{id} — Get message by message id
PUT /conversations/messages/{messageId}/attachments — Add message attachments
GET /conversations/messages/{messageId}/locations/{locationId}/recording — Get Recording by Message ID
DELETE /conversations/messages/{messageId}/schedule — Cancel a scheduled message.
PUT /conversations/messages/{messageId}/status — Update message status
GET /conversations/preferences/custom-subtypes — Get All Custom Subtypes
POST /conversations/preferences/custom-subtypes — Create Custom Subtype
PUT /conversations/preferences/custom-subtypes/{id} — Update Custom Subtype
GET /conversations/preferences/unsubscriptions/status — Get Contact Unsubscription Status
POST /conversations/preferences/unsubscriptions/user-change — User Subscription Change
POST /conversations/providers/live-chat/typing — Agent/Ai-Bot is typing a message indicator for live chat
GET /conversations/search — Search Conversations
DELETE /conversations/{conversationId} — Delete Conversation
GET /conversations/{conversationId} — Get Conversation
PUT /conversations/{conversationId} — Update Conversation
GET /conversations/{conversationId}/messages — Get messages by conversation id

POST /conversations/

Summary: Create Conversation

Creates a new conversation with the data provided

Version Header: 2021-04-15

Operation ID: create-conversation

Tags: Conversations

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST conversations",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

locationId (string) (required) (e.g. tDtDnQdgm2LXpyiqYvZ6): Location ID as string
contactId (string) (required) (e.g. tDtDnQdgm2LXpyiqYvZ6): Contact ID as string

Response Codes

Code	Description	Schema
`201`	Successful response	- success (boolean) (required) (e.g. `True`): Indicates whether the API request was successful. - conversation (string) (required): Con...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/locations/{locationId}/messages/{messageId}/transcription

Summary: Get transcription by Message ID

Get the recording transcription for a message by passing the message id

Version Header: 2021-04-15

Operation ID: get-message-transcription

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET transcription",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Path	`string`	✅	Location ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]
`messageId`	Path	`string`	✅	Message ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Response Codes

Code	Description	Schema
`200`	Gives the attached recording transcription to the message	- mediaChannel (number) (required) (e.g. `1`): Media channel describes the user interaction channel - sentenceIndex (number) (required)...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/locations/{locationId}/messages/{messageId}/transcription/download

Summary: Download transcription by Message ID

Download the recording transcription for a message by passing the message id

Version Header: 2021-04-15

Operation ID: download-message-transcription

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription/download' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription/download', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET download",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/locations/tDtDnQdgm2LXpyiqYvZ6/messages/tDtDnQdgm2LXpyiqYvZ6/transcription/download",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Path	`string`	✅	Location ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]
`messageId`	Path	`string`	✅	Message ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Response Codes

Code	Description	Schema
`200`	Downloads the attached transcription of the message	—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/messages

Summary: Send a new message

Post the necessary fields for the API to send a new message.

Version Header: 2021-04-15

Operation ID: send-a-new-message

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST messages",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

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

Response Codes

Code	Description	Schema
`200`	Created the message	- conversationId (string) (required) (e.g. `ABC12h2F6uBrIkfXYazb`): Conversation ID. - emailMessageId (string) (e.g. `rnGyqh2F6uBrIkfhF...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

DELETE /conversations/messages/email/{emailMessageId}/schedule

Summary: Cancel a scheduled email message.

Post the messageId for the API to delete a scheduled email message.

Version Header: Not required

Operation ID: cancel-scheduled-email-message

Tags: Email

cURL

curl -X DELETE 'https://rest.gohighlevel.com/v1/conversations/messages/email/ve9EPM428h8vShlRW1KT/schedule' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('DELETE', '/v1/conversations/messages/email/ve9EPM428h8vShlRW1KT/schedule', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - DELETE schedule",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "DELETE",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/email/ve9EPM428h8vShlRW1KT/schedule",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`emailMessageId`	Path	`string`	✅	Email Message Id [example: `ve9EPM428h8vShlRW1KT`]

Response Codes

Code	Description	Schema
`200`	The scheduled email message was cancelled successfully	- status (number) (required) (e.g. `404`): HTTP Status code of the request - message (string) (required) (e.g. `Failed cancel the sched...

⚠️ Special Notes & Quirks

GET /conversations/messages/email/{id}

Summary: Get email by Id

Get email by Id

Version Header: Not required

Operation ID: get-email-by-id

Tags: Email

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/messages/email/{id}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/messages/email/{id}', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET {id}",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/email/{id}",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Response Codes

Code	Description	Schema
`200`	Email object for the id given.	- id (string) (required) (e.g. `ve9EPM428h8vShlRW1KT`) - altId (string) (e.g. `ve9EPM428h8vShlRW1KT`): External Id - threadId (st...

⚠️ Special Notes & Quirks

GET /conversations/messages/export

Summary: Export messages by location ID

Export messages for a specific location with cursor-based pagination support. Response includes messageType (string), source, and subType fields. The channel parameter is optional - if not provided, all non-email message types will be returned including activity messages (opportunity updates, appointments, etc.).

Version Header: 2021-04-15

Operation ID: export-messages-by-location

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/messages/export?locationId=VALUE&limit=VALUE&cursor=eyJwaXRJZCI6ImFiYy0xMjMiLCJsYXN0U29ydCI6WzE2NDY4NjQ0MDBdLCJsYXN0SWQiOiIxMjMifQ==&sortBy=createdAt&sortOrder=asc&conversationId=VALUE&contactId=VALUE&channel=Call&startDate=VALUE&endDate=VALUE' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/messages/export?locationId=VALUE&limit=VALUE&cursor=eyJwaXRJZCI6ImFiYy0xMjMiLCJsYXN0U29ydCI6WzE2NDY4NjQ0MDBdLCJsYXN0SWQiOiIxMjMifQ==&sortBy=VALUE&sortOrder=VALUE&conversationId=VALUE&contactId=VALUE&channel=VALUE&startDate=VALUE&endDate=VALUE', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET export",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/export",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "VALUE"
        },
        {
          "name": "limit",
          "value": "VALUE"
        },
        {
          "name": "cursor",
          "value": "eyJwaXRJZCI6ImFiYy0xMjMiLCJsYXN0U29ydCI6WzE2NDY4NjQ0MDBdLCJsYXN0SWQiOiIxMjMifQ=="
        },
        {
          "name": "sortBy",
          "value": "VALUE"
        },
        {
          "name": "sortOrder",
          "value": "VALUE"
        },
        {
          "name": "conversationId",
          "value": "VALUE"
        },
        {
          "name": "contactId",
          "value": "VALUE"
        },
        {
          "name": "channel",
          "value": "VALUE"
        },
        {
          "name": "startDate",
          "value": "VALUE"
        },
        {
          "name": "endDate",
          "value": "VALUE"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Query	`string`	✅	Location ID to filter messages by
`limit`	Query	`number`	—	Number of messages to return per page
`cursor`	Query	`string`	—	Cursor for pagination. Pass the nextCursor from previous response to get next page. [example: `ey...
`sortBy`	Query	`string`	—	Field to sort by (values: createdAt, updatedAt)
`sortOrder`	Query	`string`	—	Sort order (values: asc, desc)
`conversationId`	Query	`string`	—	Filter messages by conversation ID
`contactId`	Query	`string`	—	Filter messages by contact ID
`channel`	Query	`string`	—	Filter by message channel. If not provided, all non-email message types will be returned includin...
`startDate`	Query	`string`	—	Start date to filter messages by
`endDate`	Query	`string`	—	End date to filter messages by

Response Codes

Code	Description	Schema
`200`	List of messages for the location with pagination details.	- messages (array of GetMessageResponseDto) (required): Array of messages - nextCursor (string) (e.g. `eyJwaXRJZCI6ImFiYy0xMjMiLCJsYXN0...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/messages/inbound

Summary: Add an inbound message

Post the necessary fields for the API to add a new inbound message.

Version Header: 2021-04-15

Operation ID: add-an-inbound-message

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/inbound' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages/inbound', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST inbound",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/inbound",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

type (string) (required) (e.g. SMS): Message Type
attachments (array): Array of attachments
message (string): Message Body
conversationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Conversation Id
contactId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Contact Id
conversationProviderId (string) (required) (e.g. 61d6d1f9cdac7612faf80753): Conversation Provider Id
html (string): HTML Body of Email
subject (string): Subject of the Email
emailFrom (string) (e.g. sender@company.com): Email address to send from. This field is associated with the contact record and cannot be dynamically changed.
emailTo (string): Recipient email address. This field is associated with the contact record and cannot be dynamically changed.
emailCc (array) (e.g. ['john1@doe.com', 'john2@doe.com']): List of email address to CC
emailBcc (array) (e.g. ['john1@doe.com', 'john2@doe.com']): List of email address to BCC
emailMessageId (string): Send the email message id for which this email should be threaded. This is for replying to a specific email
altId (string) (e.g. 61d6d1f9cdac7612faf80753): external mail provider's message id
direction (object) (e.g. ['outbound', 'inbound']): Message direction, if required can be set manually, default is outbound
date (string): Date of the inbound message
call (string): Phone call dialer and receiver information

Response Codes

Code	Description	Schema
`200`	Created the message	- success (boolean) (required) - conversationId (string) (required) (e.g. `ABC12h2F6uBrIkfXYazb`): Conversation ID. - messageId (...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/messages/outbound

Summary: Add an external outbound call

Post the necessary fields for the API to add a new outbound call.

Version Header: 2021-04-15

Operation ID: add-an-outbound-message

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/outbound' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages/outbound', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST outbound",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/outbound",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

type (string) (required) (e.g. Call): Message Type
attachments (array): Array of attachments
conversationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Conversation Id
conversationProviderId (string) (required) (e.g. 61d6d1f9cdac7612faf80753): Conversation Provider Id
altId (string) (e.g. 61d6d1f9cdac7612faf80753): external mail provider's message id
date (string): Date of the outbound message
call (string): Phone call dialer and receiver information

Response Codes

Code	Description	Schema
`200`	Created the message	- success (boolean) (required) - conversationId (string) (required) (e.g. `ABC12h2F6uBrIkfXYazb`): Conversation ID. - messageId (...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/messages/review-reply

Summary: Send a review reply to Google My Business

Post a reply to a customer review on Google My Business

Version Header: 2021-04-15

Operation ID: send-review-reply

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/review-reply' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages/review-reply', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST review-reply",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/review-reply",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

conversationId (string) (required) (e.g. conv123): Conversation ID (must have reviewId)
locationId (string) (required) (e.g. loc123): Location ID
message (string) (required) (e.g. Thank you for your review!): Review reply message text

Response Codes

Code	Description	Schema
`200`	Review reply sent successfully	- conversationId (string) (required) (e.g. `ABC12h2F6uBrIkfXYazb`): Conversation ID. - emailMessageId (string) (e.g. `rnGyqh2F6uBrIkfhF...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/messages/upload

Summary: Upload file attachments

Post the necessary fields for the API to upload files. The files need to be a buffer with the key "fileAttachment".

The allowed file types are:

JPG
JPEG
PNG
MP4
MPEG
ZIP
RAR
PDF
DOC
DOCX
TXT
MP3
WAV

The API will return an object with the URLs

Version Header: 2021-04-15

Operation ID: upload-file-attachments

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/upload' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('POST', '/v1/conversations/messages/upload', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST upload",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/upload",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Response Codes

Code	Description	Schema
`200`	Uploaded the file successfully	- uploadedFiles (object) (required) - twilioMediaSids (array) (e.g. `['MExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']`): Twilio media SIDs for gr...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.
`413`	Payload Too Large	- status (number) (required) (e.g. `413`): HTTP Status code of the request - message (string) (required) (e.g. `Failed to upload the fi...
`415`	Unsupported Media Type	- status (number) (required) (e.g. `413`): HTTP Status code of the request - message (string) (required) (e.g. `Failed to upload the fi...

⚠️ Special Notes & Quirks

POST /conversations/messages/upload/complete

Summary: Complete file upload

Validates the uploaded file in GCS and returns the public URL. Call this endpoint after successfully uploading the file to the signed URL.

Version Header: 2021-04-15

Operation ID: complete-file-upload

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/upload/complete' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages/upload/complete', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST complete",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/upload/complete",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

uploadId (string) (required) (e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890): Upload ID from request response
filePath (string) (required) (e.g. location/loc123/conversations/conv456/uuid.mp4): File path from request response
locationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Location ID
conversationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Conversation ID
filename (string) (required) (e.g. video.mp4): Original filename (for response mapping)

Response Codes

Code	Description	Schema
`200`	Upload completed successfully	- uploadedFiles (object) (required) (e.g. `{'video.mp4': 'https://your-domain.com/conversations-assets/location/.../video.mp4'}`): Map of fil...
`400`	Bad Request - Invalid parameters	—
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.
`404`	File not found in storage - upload may have failed or URL expired	—

⚠️ Special Notes & Quirks

POST /conversations/messages/upload/initiate

Summary: Initiate file upload to GCS

Generates a signed URL for direct file upload to Google Cloud Storage. Returns a signed URL valid for 15 minutes. Upload file via PUT request, then call /complete to finalize.

Version Header: 2021-04-15

Operation ID: initiate-file-upload

Tags: Messages

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/messages/upload/initiate' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/messages/upload/initiate', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST initiate",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/upload/initiate",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

locationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Location ID
conversationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Conversation ID
filename (string) (required) (e.g. video.mp4): Original filename with extension
contentType (string) (required) (e.g. video/mp4): MIME type of the file
fileSize (number) (e.g. 52428800): File size in bytes (optional, for pre-validation)
channel (string) (required) (e.g. WHATSAPP): Channel type for size limits (WHATSAPP for 100MB limit, others for 5MB)

Response Codes

Code	Description	Schema
`200`	Signed URL generated successfully	- uploadUrl (string) (required) (e.g. `https://storage.googleapis.com/bucket/path?X-Goog-Algorithm=...`): Signed URL for direct upload to GCS...
`400`	Bad Request - Invalid parameters	—
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.
`413`	File size exceeds maximum allowed limit	—

⚠️ Special Notes & Quirks

GET /conversations/messages/{id}

Summary: Get message by message id

Get message by message id.

Version Header: 2021-04-15

Operation ID: get-message

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/messages/{id}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/messages/{id}', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET {id}",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/{id}",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Response Codes

Code	Description	Schema
`200`	Message object for the id given.	- id (string) (required) (e.g. `ve9EPM428h8vShlRW1KT`) - type (number) (required) (e.g. `1`) - messageType (string) (required) (e...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

PUT /conversations/messages/{messageId}/attachments

Summary: Add message attachments

Set attachments on an existing message (replaces existing). Maximum 5 URLs. Supported for TYPE_CUSTOM_CALL (34) and TYPE_CALL (1) with subType EXTERNAL_CALL.

Version Header: 2021-04-15

Operation ID: add-message-attachments

Tags: Messages

cURL

curl -X PUT 'https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/attachments' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('PUT', '/v1/conversations/messages/ve9EPM428h8vShlRW1KT/attachments', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - PUT attachments",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "PUT",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/attachments",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`messageId`	Path	`string`	✅	Message Id [example: `ve9EPM428h8vShlRW1KT`]

Request Body Schema

attachments (array) (required) (e.g. ['https://provider.com/recordings/call-123.mp3']): Array of attachment URLs to set on the message (replaces existing). Maximum 5 URLs.

Response Codes

Code	Description	Schema
`200`	Successfully set message attachments	—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.
`403`	Message type does not support attachment updates	—
`404`	Message not found	—

⚠️ Special Notes & Quirks

GET /conversations/messages/{messageId}/locations/{locationId}/recording

Summary: Get Recording by Message ID

Get the recording for a message by passing the message id

Version Header: 2021-04-15

Operation ID: get-message-recording

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/messages/tDtDnQdgm2LXpyiqYvZ6/locations/tDtDnQdgm2LXpyiqYvZ6/recording' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/messages/tDtDnQdgm2LXpyiqYvZ6/locations/tDtDnQdgm2LXpyiqYvZ6/recording', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET recording",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/tDtDnQdgm2LXpyiqYvZ6/locations/tDtDnQdgm2LXpyiqYvZ6/recording",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Path	`string`	✅	Location ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]
`messageId`	Path	`string`	✅	Message ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Response Codes

Code	Description	Schema
`200`	Gives the attached recording to the message	—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

DELETE /conversations/messages/{messageId}/schedule

Summary: Cancel a scheduled message.

Post the messageId for the API to delete a scheduled message.

Version Header: 2021-04-15

Operation ID: cancel-scheduled-message

Tags: Messages

cURL

curl -X DELETE 'https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/schedule' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('DELETE', '/v1/conversations/messages/ve9EPM428h8vShlRW1KT/schedule', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - DELETE schedule",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "DELETE",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/schedule",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`messageId`	Path	`string`	✅	Message Id [example: `ve9EPM428h8vShlRW1KT`]

Response Codes

Code	Description	Schema
`200`	The scheduled message was cancelled successfully	- status (number) (required) (e.g. `404`): HTTP Status code of the request - message (string) (required) (e.g. `Failed cancel the sched...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

PUT /conversations/messages/{messageId}/status

Summary: Update message status

Post the necessary fields for the API to update message status.

Version Header: 2021-04-15

Operation ID: update-message-status

Tags: Messages

cURL

curl -X PUT 'https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/status' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('PUT', '/v1/conversations/messages/ve9EPM428h8vShlRW1KT/status', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - PUT status",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "PUT",
    "url": "https://rest.gohighlevel.com/v1/conversations/messages/ve9EPM428h8vShlRW1KT/status",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`messageId`	Path	`string`	✅	Message Id [example: `ve9EPM428h8vShlRW1KT`]

Request Body Schema

status (string) (required) (e.g. read): Message status
error (string): Error object from the conversation provider
emailMessageId (string) (e.g. ve9EPM428h8vShlRW1KT): Email message Id
recipients (array): Email delivery status for additional email recipients.

Response Codes

Code	Description	Schema
`200`	Created the message	- conversationId (string) (required) (e.g. `ABC12h2F6uBrIkfXYazb`): Conversation ID. - emailMessageId (string) (e.g. `rnGyqh2F6uBrIkfhF...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/preferences/custom-subtypes

Summary: Get All Custom Subtypes

Get all custom subtypes for a location

Version Header: 2021-04-15

Operation ID: get-all-custom-subtypes

Tags: Preference Management

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes?locationId=ve9EPM428h8vShlRW1KT' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/preferences/custom-subtypes?locationId=ve9EPM428h8vShlRW1KT', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET custom-subtypes",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "ve9EPM428h8vShlRW1KT"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Query	`string`	✅	Location Id [example: `ve9EPM428h8vShlRW1KT`]

Response Codes

Code	Description	Schema
`200`		—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/preferences/custom-subtypes

Summary: Create Custom Subtype

Create a new custom subtype for a location. Requires agency or account admin role.

Version Header: 2021-04-15

Operation ID: create-custom-subtype

Tags: Preference Management

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes?locationId=ve9EPM428h8vShlRW1KT' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/preferences/custom-subtypes?locationId=ve9EPM428h8vShlRW1KT', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST custom-subtypes",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "ve9EPM428h8vShlRW1KT"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Query	`string`	✅	Location Id [example: `ve9EPM428h8vShlRW1KT`]

Request Body Schema

name (string) (required) (e.g. Newsletter Subscription): Name of the custom subtype (max 100 characters)
description (string) (e.g. Weekly newsletter subscription preferences): Description of the custom subtype (max 100 characters)
channel (string) (required) (e.g. email): Communication channel
language (string) (required) (e.g. en): Language code

Response Codes

Code	Description	Schema
`200`	Successful response	—
`201`		—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

PUT /conversations/preferences/custom-subtypes/{id}

Summary: Update Custom Subtype

Update or archive a custom subtype. Requires agency or account admin role.

Version Header: 2021-04-15

Operation ID: update-custom-subtype

Tags: Preference Management

cURL

curl -X PUT 'https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes/ve9EPM428h8vShlRW1KT?locationId=ve9EPM428h8vShlRW1KT' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('PUT', '/v1/conversations/preferences/custom-subtypes/ve9EPM428h8vShlRW1KT?locationId=ve9EPM428h8vShlRW1KT', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - PUT ve9EPM428h8vShlRW1KT",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "PUT",
    "url": "https://rest.gohighlevel.com/v1/conversations/preferences/custom-subtypes/ve9EPM428h8vShlRW1KT",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "ve9EPM428h8vShlRW1KT"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`id`	Path	`string`	✅	Custom Subtype Id [example: `ve9EPM428h8vShlRW1KT`]
`locationId`	Query	`string`	✅	Location Id [example: `ve9EPM428h8vShlRW1KT`]

Request Body Schema

name (string) (e.g. Newsletter Subscription): Name of the custom subtype (max 100 characters)
description (string) (e.g. Updated weekly newsletter subscription preferences): Description of the custom subtype (max 100 characters)
archived (boolean) (e.g. False): Whether the custom subtype is archived
resubscription_legal_form_id (string) (e.g. form_123456): Resubscription legal form ID (optional when archiving)

Response Codes

Code	Description	Schema
`200`		—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/preferences/unsubscriptions/status

Summary: Get Contact Unsubscription Status

Get all subscription statuses for a contact (all emails or specific email)

Version Header: 2021-04-15

Operation ID: get-contact-unsubscription-status

Tags: Preference Management

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/preferences/unsubscriptions/status?locationId=ve9EPM428h8vShlRW1KT&contactId=OP7z4LCyPACyH5fcEIZa&email=user@example.com' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/preferences/unsubscriptions/status?locationId=ve9EPM428h8vShlRW1KT&contactId=OP7z4LCyPACyH5fcEIZa&email=user@example.com', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET status",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/preferences/unsubscriptions/status",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "ve9EPM428h8vShlRW1KT"
        },
        {
          "name": "contactId",
          "value": "OP7z4LCyPACyH5fcEIZa"
        },
        {
          "name": "email",
          "value": "user@example.com"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Query	`string`	✅	Location Id [example: `ve9EPM428h8vShlRW1KT`]
`contactId`	Query	`string`	✅	Contact Id [example: `OP7z4LCyPACyH5fcEIZa`]
`email`	Query	`string`	—	Email address (optional - if not provided, gets all emails for contact) [example: `user@example.c...

Response Codes

Code	Description	Schema
`200`		—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/preferences/unsubscriptions/user-change

Summary: User Subscription Change

Process subscription change initiated by a user (admin/agent). Supports individual custom subscription changes and resub all functionality. Legal forms are automatically created for user-initiated resubscribe actions on custom subscriptions.

Version Header: 2021-04-15

Operation ID: user-subscription-change

Tags: Preference Management

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/preferences/unsubscriptions/user-change' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/preferences/unsubscriptions/user-change', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST user-change",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/preferences/unsubscriptions/user-change",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

locationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Location Id
contactId (string) (required) (e.g. OP7z4LCyPACyH5fcEIZa): Contact Id
email (string) (required) (e.g. user@example.com): Email address
subscription_action (string) (required): Subscription action details
legal_reason (string) (e.g. User requested resubscribe via customer service): Legal reason for the change (required only for resubscribe and resub_all actions)
legal_description (string) (e.g. Customer called support on 2024-01-15 requesting to be removed from newsletter): Legal description/details

Response Codes

Code	Description	Schema
`200`	Successful response	—
`201`		—
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

POST /conversations/providers/live-chat/typing

Summary: Agent/Ai-Bot is typing a message indicator for live chat

Agent/AI-Bot will call this when they are typing a message in live chat message

Version Header: 2021-04-15

Operation ID: live-chat-agent-typing

Tags: Providers

cURL

curl -X POST 'https://rest.gohighlevel.com/v1/conversations/providers/live-chat/typing' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('POST', '/v1/conversations/providers/live-chat/typing', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - POST typing",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://rest.gohighlevel.com/v1/conversations/providers/live-chat/typing",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Body Schema

locationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Location Id
isTyping (string) (required) (e.g. True): Typing status
visitorId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): visitorId is the Unique ID assigned to each Live chat visitor. visitorId will be added soon in GET Contact API
conversationId (string) (required) (e.g. ve9EPM428h8vShlRW1KT): Conversation Id

Response Codes

Code	Description	Schema
`201`	Show typing indicator for live chat	- success (boolean) (required)
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.
`422`	Unprocessable Entity	Standard error response for unprocessable entity (422). Contains message, statusCode, errors array fields.

⚠️ Special Notes & Quirks

GET /conversations/search

Summary: Search Conversations

Returns a list of all conversations matching the search criteria along with the sort and filter options selected.

Version Header: 2021-04-15

Operation ID: search-conversation

Tags: Search

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/search?locationId=ABCHkzuJQ8ZMd4Te84GK&contactId=9VEmS0si86GW6gXWU89b&assignedTo=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&followers=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&mentions=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&query=Search string&sort=asc&startAfterDate=1600854&id=ABCHkzuJQ8ZMd4Te84GK&limit=20&lastMessageType=TYPE_SMS&lastMessageAction=manual&lastMessageDirection=inbound&status=all&sortBy=last_message_date&sortScoreProfile=ABCHkzuJQ8ZMd4Te84GK&scoreProfile=ABCHkzuJQ8ZMd4Te84GK&scoreProfileMin=ABCHkzuJQ8ZMd4Te84GK&scoreProfileMax=ABCHkzuJQ8ZMd4Te84GK&startDate=1640995200000&endDate=1672531199000' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/search?locationId=ABCHkzuJQ8ZMd4Te84GK&contactId=9VEmS0si86GW6gXWU89b&assignedTo=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&followers=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&mentions=ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik&query=Search string&sort=asc&startAfterDate=1600854&id=ABCHkzuJQ8ZMd4Te84GK&limit=20&lastMessageType=TYPE_SMS&lastMessageAction=manual&lastMessageDirection=inbound&status=all&sortBy=last_message_date&sortScoreProfile=ABCHkzuJQ8ZMd4Te84GK&scoreProfile=ABCHkzuJQ8ZMd4Te84GK&scoreProfileMin=ABCHkzuJQ8ZMd4Te84GK&scoreProfileMax=ABCHkzuJQ8ZMd4Te84GK&startDate=1640995200000&endDate=1672531199000', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET search",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/search",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "locationId",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "contactId",
          "value": "9VEmS0si86GW6gXWU89b"
        },
        {
          "name": "assignedTo",
          "value": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik"
        },
        {
          "name": "followers",
          "value": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik"
        },
        {
          "name": "mentions",
          "value": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik"
        },
        {
          "name": "query",
          "value": "Search string"
        },
        {
          "name": "sort",
          "value": "asc"
        },
        {
          "name": "startAfterDate",
          "value": 1600854
        },
        {
          "name": "id",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "limit",
          "value": 20
        },
        {
          "name": "lastMessageType",
          "value": "TYPE_SMS"
        },
        {
          "name": "lastMessageAction",
          "value": "manual"
        },
        {
          "name": "lastMessageDirection",
          "value": "inbound"
        },
        {
          "name": "status",
          "value": "all"
        },
        {
          "name": "sortBy",
          "value": "last_message_date"
        },
        {
          "name": "sortScoreProfile",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "scoreProfile",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "scoreProfileMin",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "scoreProfileMax",
          "value": "ABCHkzuJQ8ZMd4Te84GK"
        },
        {
          "name": "startDate",
          "value": 1640995200000
        },
        {
          "name": "endDate",
          "value": 1672531199000
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`locationId`	Query	`string`	✅	Location Id [example: `ABCHkzuJQ8ZMd4Te84GK`]
`contactId`	Query	`string`	—	Contact Id [example: `9VEmS0si86GW6gXWU89b`]
`assignedTo`	Query	`string`	—	User IDs that conversations are assigned to. Multiple IDs can be provided as comma-separated valu...
`followers`	Query	`string`	—	User IDs of followers to filter conversations by. Multiple IDs can be provided as comma-separated...
`mentions`	Query	`string`	—	User Id of the mention. Multiple values are comma separated. [example: `ABCHkzuJQ8ZMd4Te84GK,fGia...
`query`	Query	`string`	—	Search paramater as a string [example: `Search string`]
`sort`	Query	`string`	—	Sort paramater - asc or desc (values: asc, desc) [example: `asc`]
`startAfterDate`	Query	`any`	—	Search to begin after the specified date - should contain the sort value of the last document [ex...
`id`	Query	`string`	—	Id of the conversation [example: `ABCHkzuJQ8ZMd4Te84GK`]
`limit`	Query	`number`	—	Limit of conversations - Default is 20 [example: `20`]
`lastMessageType`	Query	`string`	—	Type of the last message in the conversation as a string (values: TYPE_CALL, TYPE_SMS, TYPE_RCS, ...
`lastMessageAction`	Query	`string`	—	Action of the last outbound message in the conversation as string. (values: automated, manual) [e...
`lastMessageDirection`	Query	`string`	—	Direction of the last message in the conversation as string. (values: inbound, outbound) [example...
`status`	Query	`string`	—	The status of the conversation to be filtered - all, read, unread, starred (values: all, read, u...
`sortBy`	Query	`string`	—	The sorting of the conversation to be filtered as - manual messages or all messages (values: last...
`sortScoreProfile`	Query	`string`	—	Id of score profile on which sortBy.ScoreProfile should sort on [example: `ABCHkzuJQ8ZMd4Te84GK`]
`scoreProfile`	Query	`string`	—	Id of score profile on which conversations should get filtered out, works with scoreProfileMin & ...
`scoreProfileMin`	Query	`number`	—	Minimum value for score [example: `ABCHkzuJQ8ZMd4Te84GK`]
`scoreProfileMax`	Query	`number`	—	Maximum value for score [example: `ABCHkzuJQ8ZMd4Te84GK`]
`startDate`	Query	`number`	—	Start date filter for dateAdded field (Unix timestamp in milliseconds) [example: `1640995200000`]
`endDate`	Query	`number`	—	End date filter for dateAdded field (Unix timestamp in milliseconds) [example: `1672531199000`]

Response Codes

Code	Description	Schema
`200`	Successfully fetched the conversations	- conversations (array of ConversationSchema) (required): The list of all conversations found for the given query - total (number) (req...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

DELETE /conversations/{conversationId}

Summary: Delete Conversation

Delete the conversation details based on the conversation ID

Version Header: 2021-04-15

Operation ID: delete-conversation

Tags: Conversations

cURL

curl -X DELETE 'https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('DELETE', '/v1/conversations/tDtDnQdgm2LXpyiqYvZ6', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - DELETE tDtDnQdgm2LXpyiqYvZ6",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "DELETE",
    "url": "https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`conversationId`	Path	`string`	✅	Conversation ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Response Codes

Code	Description	Schema
`200`	Successful response	- success (boolean) (required) (e.g. `True`): Boolean value as the API response.
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/{conversationId}

Summary: Get Conversation

Get the conversation details based on the conversation ID

Version Header: 2021-04-15

Operation ID: get-conversation

Tags: Conversations

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/tDtDnQdgm2LXpyiqYvZ6', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET tDtDnQdgm2LXpyiqYvZ6",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`conversationId`	Path	`string`	✅	Conversation ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Response Codes

Code	Description	Schema
`200`	Successful response	- contactId (string) (required) (e.g. `ve9EPM428kjkvShlRW1KT`): Unique identifier of the contact associated with this conversation - **loca...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

PUT /conversations/{conversationId}

Summary: Update Conversation

Update the conversation details based on the conversation ID

Version Header: 2021-04-15

Operation ID: update-conversation

Tags: Conversations

cURL

curl -X PUT 'https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{}'  # See request body schema below

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

payload = json.dumps({})
conn.request('PUT', '/v1/conversations/tDtDnQdgm2LXpyiqYvZ6', body=payload, headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - PUT tDtDnQdgm2LXpyiqYvZ6",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "PUT",
    "url": "https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": []
    },
    "options": {}
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`conversationId`	Path	`string`	✅	Conversation ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]

Request Body Schema

locationId (string) (required) (e.g. tDtDnQdgm2LXpyiqYvZ6): Location ID as string
unreadCount (number) (e.g. 1): Count of unread messages in the conversation
starred (boolean) (e.g. True): Starred status of the conversation.
feedback (object)

Response Codes

Code	Description	Schema
`200`	Successful response	- success (boolean) (required) (e.g. `True`): Boolean value as the API response. - conversation (string) (required): Conversation data ...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

GET /conversations/{conversationId}/messages

Summary: Get messages by conversation id

Get messages by conversation id.

Version Header: 2021-04-15

Operation ID: get-messages

Tags: Messages

cURL

curl -X GET 'https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6/messages?lastMessageId=tDtDnQdgm2LXpyiqYvZ6&limit=20&type=TYPE_SMS,TYPE_CALL' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Version: 2021-04-15' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'User-Agent: YourApp/1.0'

Python (http.client)

import http.client
import json

conn = http.client.HTTPSConnection('rest.gohighlevel.com')

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Version': '2021-04-15',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'YourApp/1.0',
}

conn.request('GET', '/v1/conversations/tDtDnQdgm2LXpyiqYvZ6/messages?lastMessageId=tDtDnQdgm2LXpyiqYvZ6&limit=20&type=TYPE_SMS,TYPE_CALL', headers=headers)

response = conn.getresponse()
data = json.loads(response.read().decode())
print(json.dumps(data, indent=2))
conn.close()

n8n HTTP Node

{
  "name": "GHL - GET messages",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://rest.gohighlevel.com/v1/conversations/tDtDnQdgm2LXpyiqYvZ6/messages",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_TOKEN"
        },
        {
          "name": "Version",
          "value": "2021-04-15"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        },
        {
          "name": "User-Agent",
          "value": "YourApp/1.0"
        }
      ]
    },
    "sendBody": false,
    "bodyParameters": {
      "parameters": []
    },
    "options": {},
    "sendQuery": true,
    "queryParameters": {
      "parameters": [
        {
          "name": "lastMessageId",
          "value": "tDtDnQdgm2LXpyiqYvZ6"
        },
        {
          "name": "limit",
          "value": 20
        },
        {
          "name": "type",
          "value": "TYPE_SMS,TYPE_CALL"
        }
      ]
    }
  }
}

To use in n8n:

Add an HTTP Request node
Switch to JSON mode (Parameters → use RAW JSON)
Paste the JSON above
Update YOUR_API_TOKEN with your actual GHL API key

Request Parameters

Name	Location	Type	Required	Description
`conversationId`	Path	`string`	✅	Conversation ID as string [example: `tDtDnQdgm2LXpyiqYvZ6`]
`lastMessageId`	Query	`string`	—	Message ID of the last message in the list as a string [example: `tDtDnQdgm2LXpyiqYvZ6`]
`limit`	Query	`number`	—	Number of messages to be fetched from the conversation. Default limit is 20 [example: `20`]
`type`	Query	`string`	—	Types of message to fetched separated with comma (values: TYPE_CALL, TYPE_SMS, TYPE_RCS, TYPE_EMA...

Response Codes

Code	Description	Schema
`200`	List of messages for the conversation id of the given type.	- lastMessageId (string) (required) (e.g. `p1mRSHeLDhAms5q0LMr4`): Id of the last message in the messages array - nextPage (boolean) (r...
`400`	Bad Request	Standard error response for bad requests (400). Contains message, statusCode fields.
`401`	Unauthorized	Standard error response for unauthorized requests (401). Contains message, statusCode fields.

⚠️ Special Notes & Quirks

Documentation generated from GHL OpenAPI specifications. Verify against official docs for latest changes.

111 KiB Raw Blame History

GHL Conversations API

Endpoints

POST /conversations/

cURL

Python (http.client)

n8n HTTP Node

Request Body Schema

Response Codes

⚠️ Special Notes & Quirks

GET /conversations/locations/{locationId}/messages/{messageId}/transcription

cURL

Python (http.client)

n8n HTTP Node

Request Parameters

Response Codes

⚠️ Special Notes & Quirks

GET /conversations/locations/{locationId}/messages/{messageId}/transcription/download

cURL

Python (http.client)

n8n HTTP Node

Request Parameters

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages

cURL

Python (http.client)

n8n HTTP Node

Request Body Schema

Response Codes

⚠️ Special Notes & Quirks

DELETE /conversations/messages/email/{emailMessageId}/schedule

cURL

Python (http.client)

n8n HTTP Node

Request Parameters

Response Codes

⚠️ Special Notes & Quirks

GET /conversations/messages/email/{id}

cURL

Python (http.client)

n8n HTTP Node

Response Codes

⚠️ Special Notes & Quirks

GET /conversations/messages/export

cURL

Python (http.client)

n8n HTTP Node

Request Parameters

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages/inbound

cURL

Python (http.client)

n8n HTTP Node

Request Body Schema

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages/outbound

cURL

Python (http.client)

n8n HTTP Node

Request Body Schema

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages/review-reply

cURL

Python (http.client)

n8n HTTP Node

Request Body Schema

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages/upload

cURL

Python (http.client)

n8n HTTP Node

Response Codes

⚠️ Special Notes & Quirks

POST /conversations/messages/upload/complete

cURL

111 KiB

Raw Blame History