# Send a new message

POST https://services.leadconnectorhq.com/conversations/messages

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

## Authentication

Send `Authorization: Bearer <token>` using:

- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `conversations/message.write`

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Version` | string | Yes | API Version |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "HighLevel API",
    "version": "v4"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/conversations/messages": {
      "post": {
        "summary": "Send a new message",
        "operationId": "sendANewMessage",
        "description": "Post the necessary fields for the API to send a new message.",
        "parameters": [
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v4"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessageBodyDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created the message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestDTO"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": [
              "conversations/message.write"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account.",
        "type": "http"
      },
      "Agency-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
        "type": "http"
      }
    },
    "schemas": {
      "SendMessageBodyDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "SMS",
              "Email",
              "WhatsApp",
              "IG",
              "FB",
              "Custom",
              "Live_Chat",
              "InternalComment"
            ],
            "description": "Type of message being sent",
            "example": "Email"
          },
          "contactId": {
            "type": "string",
            "description": "ID of the contact receiving the message",
            "example": "abc123def456"
          },
          "appointmentId": {
            "type": "string",
            "description": "ID of the associated appointment",
            "example": "appt123"
          },
          "attachments": {
            "description": "Array of attachment URLs",
            "example": [
              "https://storage.com/file1.pdf",
              "https://storage.com/file2.jpg"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "emailFrom": {
            "type": "string",
            "description": "Email address to send from",
            "example": "sender@company.com"
          },
          "emailCc": {
            "description": "Array of CC email addresses",
            "example": [
              "cc1@company.com",
              "cc2@company.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "emailBcc": {
            "description": "Array of BCC email addresses",
            "example": [
              "bcc1@company.com",
              "bcc2@company.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "html": {
            "type": "string",
            "description": "HTML content of the message",
            "example": "<p>Hello World</p>"
          },
          "message": {
            "type": "string",
            "description": "Text content of the message. For InternalComment type, use `@username<userId>actualUserId</userId>` format to mention team members. The mentioned user IDs must also be included in the mentions array.",
            "example": "Hello, how can I help you today?"
          },
          "subject": {
            "type": "string",
            "description": "Subject line for email messages",
            "example": "Important Update"
          },
          "replyMessageId": {
            "type": "string",
            "description": "ID of message being replied to",
            "example": "msg123"
          },
          "templateId": {
            "type": "string",
            "description": "ID of message template",
            "example": "template123"
          },
          "threadId": {
            "type": "string",
            "description": "ID of message thread. For email messages, this is the message ID that contains multiple email messages in the thread",
            "example": "thread123"
          },
          "scheduledTimestamp": {
            "type": "number",
            "description": "UTC Timestamp (in seconds) at which the message should be scheduled",
            "example": 1669287863
          },
          "conversationProviderId": {
            "type": "string",
            "description": "ID of conversation provider",
            "example": "provider123"
          },
          "emailTo": {
            "type": "string",
            "description": "Email address to send to, if different from contact's primary email. This should be a valid email address associated with the contact.",
            "example": "recipient@company.com"
          },
          "emailReplyMode": {
            "type": "string",
            "enum": [
              "reply",
              "reply_all"
            ],
            "description": "Mode for email replies",
            "example": "reply_all"
          },
          "fromNumber": {
            "type": "string",
            "description": "Phone number used as the sender number for outbound messages",
            "example": "+1499499299"
          },
          "toNumber": {
            "type": "string",
            "description": "Recipient phone number for outbound messages",
            "example": "+1439499299"
          },
          "status": {
            "type": "string",
            "description": "Message status",
            "example": "delivered",
            "enum": [
              "delivered",
              "failed",
              "pending",
              "read"
            ]
          },
          "mentions": {
            "description": "Array of user IDs mentioned in the message. Required for InternalComment type. User IDs correspond to team members tagged with `@username<userId>id</userId>` format in the message text.",
            "example": [
              "userId123",
              "userId456"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "userId": {
            "type": "string",
            "description": "Use this field to specify the user who is making the internal comment when type is 'InternalComment'. If not provided, the comment will be attributed to the system or default user.",
            "example": "user123"
          }
        },
        "required": [
          "type",
          "contactId",
          "status"
        ],
        "title": "SendMessageBodyDto"
      },
      "SendMessageResponseDto": {
        "type": "object",
        "properties": {
          "conversationId": {
            "type": "string",
            "description": "Conversation ID.",
            "example": "ABC12h2F6uBrIkfXYazb"
          },
          "emailMessageId": {
            "type": "string",
            "description": "This contains the email message id (only for Email type). Use this ID to send inbound replies to CRM to create a threaded email.",
            "example": "rnGyqh2F6uBrIkfhFo9A"
          },
          "messageId": {
            "type": "string",
            "description": "This is the main Message ID",
            "example": "t22c6DQcTDf3MjRhwf77"
          },
          "messageIds": {
            "description": "When sending via the GMB channel, we will be returning list of `messageIds` instead of single `messageId`.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "msg": {
            "type": "string",
            "description": "Additional response message when sending a workflow message",
            "example": "Message queued successfully."
          }
        },
        "required": [
          "conversationId",
          "messageId"
        ],
        "title": "SendMessageResponseDto"
      },
      "BadRequestDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "Bad Request"
          }
        },
        "title": "BadRequestDTO"
      },
      "UnauthorizedDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 401
          },
          "message": {
            "type": "string",
            "example": "Invalid token: access token is invalid"
          },
          "error": {
            "type": "string",
            "example": "Unauthorized"
          }
        },
        "title": "UnauthorizedDTO"
      }
    }
  }
}
```

## HighLevel SDK Examples

**Node.js** (`@gohighlevel/api-client`)

```javascript
import HighLevel from '@gohighlevel/api-client';

const ghl = new HighLevel({
  privateIntegrationToken: '<PRIVATE_INTEGRATION_TOKEN>'
});

const body = {
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
};

const response = await ghl.conversations.sendANewMessage(body);
console.log(response);
```

**Python** (`gohighlevel-api-client`)

```python
from highlevel import HighLevel

client = HighLevel(
    private_integration_token='<PRIVATE_INTEGRATION_TOKEN>'
)

body = {
    "type": "Email",
    "contactId": "abc123def456",
    "appointmentId": "appt123",
    "attachments": [
        "https://storage.com/file1.pdf",
        "https://storage.com/file2.jpg"
    ],
    "emailFrom": "sender@company.com",
    "emailCc": [
        "cc1@company.com",
        "cc2@company.com"
    ],
    "emailBcc": [
        "bcc1@company.com",
        "bcc2@company.com"
    ],
    "html": "<p>Hello World</p>",
    "message": "Hello, how can I help you today?",
    "subject": "Important Update",
    "replyMessageId": "msg123",
    "templateId": "template123",
    "threadId": "thread123",
    "scheduledTimestamp": 1669287863,
    "conversationProviderId": "provider123",
    "emailTo": "recipient@company.com",
    "emailReplyMode": "reply_all",
    "fromNumber": "+1499499299",
    "toNumber": "+1439499299",
    "status": "delivered",
    "mentions": [
        "userId123",
        "userId456"
    ],
    "userId": "user123"
}

response = await client.conversations.send_a_new_message(body=body)
print(response)
```

**PHP** (`gohighlevel/api-client`)

```php
<?php
require_once 'vendor/autoload.php';

use HighLevel\HighLevel;
use HighLevel\HighLevelConfig;

$config = new HighLevelConfig([
    'privateIntegrationToken' => '<PRIVATE_INTEGRATION_TOKEN>'
]);
$ghl = new HighLevel($config);

$body = [
    'type' => 'Email',
    'contactId' => 'abc123def456',
    'appointmentId' => 'appt123',
    'attachments' => [
        'https://storage.com/file1.pdf',
        'https://storage.com/file2.jpg'
    ],
    'emailFrom' => 'sender@company.com',
    'emailCc' => [
        'cc1@company.com',
        'cc2@company.com'
    ],
    'emailBcc' => [
        'bcc1@company.com',
        'bcc2@company.com'
    ],
    'html' => '<p>Hello World</p>',
    'message' => 'Hello, how can I help you today?',
    'subject' => 'Important Update',
    'replyMessageId' => 'msg123',
    'templateId' => 'template123',
    'threadId' => 'thread123',
    'scheduledTimestamp' => 1669287863,
    'conversationProviderId' => 'provider123',
    'emailTo' => 'recipient@company.com',
    'emailReplyMode' => 'reply_all',
    'fromNumber' => '+1499499299',
    'toNumber' => '+1439499299',
    'status' => 'delivered',
    'mentions' => [
        'userId123',
        'userId456'
    ],
    'userId' => 'user123'
];

$response = $ghl->conversations->sendANewMessage($body);
echo json_encode($response, JSON_PRETTY_PRINT);
```

## Code Examples

**cURL**

```bash
curl -L -X POST 'https://services.leadconnectorhq.com/conversations/messages' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: v4' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
}'
```

**Node.js**

```javascript
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: 'v4',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "type": "Email",
      "contactId": "abc123def456",
      "appointmentId": "appt123",
      "attachments": [
        "https://storage.com/file1.pdf",
        "https://storage.com/file2.jpg"
      ],
      "emailFrom": "sender@company.com",
      "emailCc": [
        "cc1@company.com",
        "cc2@company.com"
      ],
      "emailBcc": [
        "bcc1@company.com",
        "bcc2@company.com"
      ],
      "html": "<p>Hello World</p>",
      "message": "Hello, how can I help you today?",
      "subject": "Important Update",
      "replyMessageId": "msg123",
      "templateId": "template123",
      "threadId": "thread123",
      "scheduledTimestamp": 1669287863,
      "conversationProviderId": "provider123",
      "emailTo": "recipient@company.com",
      "emailReplyMode": "reply_all",
      "fromNumber": "+1499499299",
      "toNumber": "+1439499299",
      "status": "delivered",
      "mentions": [
        "userId123",
        "userId456"
      ],
      "userId": "user123"
  })
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/conversations/messages', options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**Python**

```python
import requests

url = "https://services.leadconnectorhq.com/conversations/messages"

headers = {
    "Authorization": "Bearer <TOKEN>",
    "Version": "v4"
}

payload = {
    "type": "Email",
    "contactId": "abc123def456",
    "appointmentId": "appt123",
    "attachments": [
        "https://storage.com/file1.pdf",
        "https://storage.com/file2.jpg"
    ],
    "emailFrom": "sender@company.com",
    "emailCc": [
        "cc1@company.com",
        "cc2@company.com"
    ],
    "emailBcc": [
        "bcc1@company.com",
        "bcc2@company.com"
    ],
    "html": "<p>Hello World</p>",
    "message": "Hello, how can I help you today?",
    "subject": "Important Update",
    "replyMessageId": "msg123",
    "templateId": "template123",
    "threadId": "thread123",
    "scheduledTimestamp": 1669287863,
    "conversationProviderId": "provider123",
    "emailTo": "recipient@company.com",
    "emailReplyMode": "reply_all",
    "fromNumber": "+1499499299",
    "toNumber": "+1439499299",
    "status": "delivered",
    "mentions": [
        "userId123",
        "userId456"
    ],
    "userId": "user123"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/conversations/messages',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: v4',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
}',
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .post("https://services.leadconnectorhq.com/conversations/messages")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "v4")
  .header("Content-Type", "application/json")
  .body("{\"type\":\"Email\",\"contactId\":\"abc123def456\",\"appointmentId\":\"appt123\",\"attachments\":[\"https://storage.com/file1.pdf\",\"https://storage.com/file2.jpg\"],\"emailFrom\":\"sender@company.com\",\"emailCc\":[\"cc1@company.com\",\"cc2@company.com\"],\"emailBcc\":[\"bcc1@company.com\",\"bcc2@company.com\"],\"html\":\"<p>Hello World</p>\",\"message\":\"Hello, how can I help you today?\",\"subject\":\"Important Update\",\"replyMessageId\":\"msg123\",\"templateId\":\"template123\",\"threadId\":\"thread123\",\"scheduledTimestamp\":1669287863,\"conversationProviderId\":\"provider123\",\"emailTo\":\"recipient@company.com\",\"emailReplyMode\":\"reply_all\",\"fromNumber\":\"+1499499299\",\"toNumber\":\"+1439499299\",\"status\":\"delivered\",\"mentions\":[\"userId123\",\"userId456\"],\"userId\":\"user123\"}")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
  "strings"
)

func main() {
  url := "https://services.leadconnectorhq.com/conversations/messages"
  payload := strings.NewReader(`{
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
}`)
  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Version", "v4")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

**Ruby**

```ruby
require 'uri'
require 'net/http'

url = URI("https://services.leadconnectorhq.com/conversations/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "v4"
request["Content-Type"] = "application/json"
request.body = '{
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
}'

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "v4"
}

$body = '{
  "type": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "status": "delivered",
  "mentions": [
    "userId123",
    "userId456"
  ],
  "userId": "user123"
}'

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/conversations/messages' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json'
$response | ConvertTo-Json
```