Send a message

curl --request POST \
  --url http://localhost:8080/chat/sessions/{session_id}/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "type": "text",
    "text": "<string>",
    "attachments": [
      {
        "name": "<string>",
        "url": "<string>",
        "base64": "<string>",
        "mime_type": "<string>"
      }
    ]
  },
  "contact": {
    "name": "<string>",
    "email": "[email protected]",
    "phone_number": "<string>",
    "avatar_url": "<string>",
    "custom_data": {}
  },
  "custom_data": {},
  "agent": {
    "id": 123,
    "name": "<string>",
    "avatar_url": "<string>"
  },
  "should_take_over_session_from_ai": false
}
'

import requests

url = "http://localhost:8080/chat/sessions/{session_id}/send"

payload = {
    "message": {
        "type": "text",
        "text": "<string>",
        "attachments": [
            {
                "name": "<string>",
                "url": "<string>",
                "base64": "<string>",
                "mime_type": "<string>"
            }
        ]
    },
    "contact": {
        "name": "<string>",
        "email": "[email protected]",
        "phone_number": "<string>",
        "avatar_url": "<string>",
        "custom_data": {}
    },
    "custom_data": {},
    "agent": {
        "id": 123,
        "name": "<string>",
        "avatar_url": "<string>"
    },
    "should_take_over_session_from_ai": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: {
      type: 'text',
      text: '<string>',
      attachments: [{name: '<string>', url: '<string>', base64: '<string>', mime_type: '<string>'}]
    },
    contact: {
      name: '<string>',
      email: '[email protected]',
      phone_number: '<string>',
      avatar_url: '<string>',
      custom_data: {}
    },
    custom_data: {},
    agent: {id: 123, name: '<string>', avatar_url: '<string>'},
    should_take_over_session_from_ai: false
  })
};

fetch('http://localhost:8080/chat/sessions/{session_id}/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/chat/sessions/{session_id}/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => [
        'type' => 'text',
        'text' => '<string>',
        'attachments' => [
                [
                                'name' => '<string>',
                                'url' => '<string>',
                                'base64' => '<string>',
                                'mime_type' => '<string>'
                ]
        ]
    ],
    'contact' => [
        'name' => '<string>',
        'email' => '[email protected]',
        'phone_number' => '<string>',
        'avatar_url' => '<string>',
        'custom_data' => [
                
        ]
    ],
    'custom_data' => [
        
    ],
    'agent' => [
        'id' => 123,
        'name' => '<string>',
        'avatar_url' => '<string>'
    ],
    'should_take_over_session_from_ai' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "http://localhost:8080/chat/sessions/{session_id}/send"

	payload := strings.NewReader("{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/chat/sessions/{session_id}/send")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/chat/sessions/{session_id}/send")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}"

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

{
  "success": true,
  "data": {
    "message": {
      "id": "<string>"
    }
  }
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

POST

chat

sessions

{session_id}

send

Send a message

curl --request POST \
  --url http://localhost:8080/chat/sessions/{session_id}/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "type": "text",
    "text": "<string>",
    "attachments": [
      {
        "name": "<string>",
        "url": "<string>",
        "base64": "<string>",
        "mime_type": "<string>"
      }
    ]
  },
  "contact": {
    "name": "<string>",
    "email": "[email protected]",
    "phone_number": "<string>",
    "avatar_url": "<string>",
    "custom_data": {}
  },
  "custom_data": {},
  "agent": {
    "id": 123,
    "name": "<string>",
    "avatar_url": "<string>"
  },
  "should_take_over_session_from_ai": false
}
'

import requests

url = "http://localhost:8080/chat/sessions/{session_id}/send"

payload = {
    "message": {
        "type": "text",
        "text": "<string>",
        "attachments": [
            {
                "name": "<string>",
                "url": "<string>",
                "base64": "<string>",
                "mime_type": "<string>"
            }
        ]
    },
    "contact": {
        "name": "<string>",
        "email": "[email protected]",
        "phone_number": "<string>",
        "avatar_url": "<string>",
        "custom_data": {}
    },
    "custom_data": {},
    "agent": {
        "id": 123,
        "name": "<string>",
        "avatar_url": "<string>"
    },
    "should_take_over_session_from_ai": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: {
      type: 'text',
      text: '<string>',
      attachments: [{name: '<string>', url: '<string>', base64: '<string>', mime_type: '<string>'}]
    },
    contact: {
      name: '<string>',
      email: '[email protected]',
      phone_number: '<string>',
      avatar_url: '<string>',
      custom_data: {}
    },
    custom_data: {},
    agent: {id: 123, name: '<string>', avatar_url: '<string>'},
    should_take_over_session_from_ai: false
  })
};

fetch('http://localhost:8080/chat/sessions/{session_id}/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/chat/sessions/{session_id}/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => [
        'type' => 'text',
        'text' => '<string>',
        'attachments' => [
                [
                                'name' => '<string>',
                                'url' => '<string>',
                                'base64' => '<string>',
                                'mime_type' => '<string>'
                ]
        ]
    ],
    'contact' => [
        'name' => '<string>',
        'email' => '[email protected]',
        'phone_number' => '<string>',
        'avatar_url' => '<string>',
        'custom_data' => [
                
        ]
    ],
    'custom_data' => [
        
    ],
    'agent' => [
        'id' => 123,
        'name' => '<string>',
        'avatar_url' => '<string>'
    ],
    'should_take_over_session_from_ai' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "http://localhost:8080/chat/sessions/{session_id}/send"

	payload := strings.NewReader("{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/chat/sessions/{session_id}/send")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/chat/sessions/{session_id}/send")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\",\n    \"attachments\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"base64\": \"<string>\",\n        \"mime_type\": \"<string>\"\n      }\n    ]\n  },\n  \"contact\": {\n    \"name\": \"<string>\",\n    \"email\": \"[email protected]\",\n    \"phone_number\": \"<string>\",\n    \"avatar_url\": \"<string>\",\n    \"custom_data\": {}\n  },\n  \"custom_data\": {},\n  \"agent\": {\n    \"id\": 123,\n    \"name\": \"<string>\",\n    \"avatar_url\": \"<string>\"\n  },\n  \"should_take_over_session_from_ai\": false\n}"

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

{
  "success": true,
  "data": {
    "message": {
      "id": "<string>"
    }
  }
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

Custom data

This endpoint accepts two independent custom_data objects, each merged into a different record:

Top-level custom_data — session-level attributes that belong to this conversation, such as an order ID, cart value, or routing flag. Merged into the chat session and returned by Get Session. Values can be strings, numbers, or booleans.
contact.custom_data — contact-level attributes that belong to the person, such as plan, region, or account tier. Merged into the contact. Values are strings.

Both merge into any existing data, so you only need to send the keys you want to add or update. Nested objects are rejected with a 400.

{
  "sender": "contact",
  "custom_data": { "order_id": "ord_123", "cart_value": 149.99, "priority": "high" },
  "contact": { "custom_data": { "plan": "pro", "region": "emea" } },
  "message": { "type": "text", "text": "I need help with this order" }
}

Session custom_data set through this endpoint is stored on the session but is not synced to a connected external ticketing system (e.g. Intercom or HubSpot).

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

session_id

string

required

The unique identifier of the chat session

Body

application/json

sender

enum<string>

required

Available options:

contact,

agent

message

object

required

Show child attributes

contact

object

Show child attributes

custom_data

object

Session-level custom data to merge into the chat session. Use contact.custom_data for contact-level attributes.

Show child attributes

agent

object

Show child attributes

should_take_over_session_from_ai

boolean

default:false

Response

Default Response

success

boolean

required

data

object

required

Option 1
Option 2
Option 3

Show child attributes

Overview

Blocklist

Autopilot

Organization

Contacts

Companies

Sessions

Connect

AI Phone Agents

AI Email

AI WhatsApp

AI Actions

AI Outbound Sequencing

Media

AI Training

Resource Usage

Customer Insights

Teams

CSAT

Redaction

Crawl

Tags

Office Hours

Handoff Analytics

SLA Analytics

Secrets

Workflows (Beta)

Salesforce MIAW

Webhooks

Send a message

Custom data

Authorizations

Path Parameters

Body

Response

​Custom data

Authorizations

Path Parameters

Body

Response

Custom data