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": "jsmith@example.com",
    "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": "jsmith@example.com",
        "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: 'jsmith@example.com',
      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' => 'jsmith@example.com',
        '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\": \"jsmith@example.com\",\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\": \"jsmith@example.com\",\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\": \"jsmith@example.com\",\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": "jsmith@example.com",
    "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": "jsmith@example.com",
        "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: 'jsmith@example.com',
      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' => 'jsmith@example.com',
        '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\": \"jsmith@example.com\",\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\": \"jsmith@example.com\",\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\": \"jsmith@example.com\",\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).

Option taps

An agent reply sent from a macro with options carries them on the conversation.agent_response webhook as options, next to the reply’s message_id, and on the message’s event.options in session history. On API sessions your client renders them. When the customer taps one, send a contact message that names the tap in message.option_reply. The message is recorded with the option’s label as its text, and an option that isn’t on a message of this session is rejected with a 400:

{
  "sender": "contact",
  "message": {
    "type": "text",
    "text": "Yes",
    "option_reply": {
      "message_id": "7c3f1a7e-2a51-4b8e-9d0f-6f1b2c3d4e5f",
      "option_id": "b1e2c3d4-0000-4a5b-8c9d-112233445566"
    }
  }
}

Only the first tap on the session’s newest message with options counts, and only while the session is open. A tap on a workflow option runs the macro’s Macro Option Clicked workflows and the AI doesn’t reply; a text option is handled like any contact message. A tap that doesn’t count, and the same text sent without option_reply, is handled as a normal message. option_reply is rejected with a 400 when sender is agent.

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

​Custom data

​Option taps

Authorizations

Path Parameters

Body

Response

Custom data

Option taps