Create Conversation
curl --request POST \
--url http://localhost:8080/api/v1/conversations \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"content": "<string>",
"inbox_id": 123,
"contact_email": "jsmith@example.com",
"first_name": "<string>",
"subject": "<string>",
"send_from": "jsmith@example.com",
"team_id": 123,
"agent_id": 123,
"cc": [
"jsmith@example.com"
],
"bcc": [
"jsmith@example.com"
],
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [
123
],
"source_id": "<string>",
"custom_attributes": {
"order_id": "A-1024",
"plan": "pro"
},
"reuse_contact": false
}
'import requests
url = "http://localhost:8080/api/v1/conversations"
payload = {
"content": "<string>",
"inbox_id": 123,
"contact_email": "jsmith@example.com",
"first_name": "<string>",
"subject": "<string>",
"send_from": "jsmith@example.com",
"team_id": 123,
"agent_id": 123,
"cc": ["jsmith@example.com"],
"bcc": ["jsmith@example.com"],
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [123],
"source_id": "<string>",
"custom_attributes": {
"order_id": "A-1024",
"plan": "pro"
},
"reuse_contact": False
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
content: '<string>',
inbox_id: 123,
contact_email: 'jsmith@example.com',
first_name: '<string>',
subject: '<string>',
send_from: 'jsmith@example.com',
team_id: 123,
agent_id: 123,
cc: ['jsmith@example.com'],
bcc: ['jsmith@example.com'],
last_name: '<string>',
external_user_id: 'crm-9f3a21',
attachments: [123],
source_id: '<string>',
custom_attributes: {order_id: 'A-1024', plan: 'pro'},
reuse_contact: false
})
};
fetch('http://localhost:8080/api/v1/conversations', 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/api/v1/conversations",
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([
'content' => '<string>',
'inbox_id' => 123,
'contact_email' => 'jsmith@example.com',
'first_name' => '<string>',
'subject' => '<string>',
'send_from' => 'jsmith@example.com',
'team_id' => 123,
'agent_id' => 123,
'cc' => [
'jsmith@example.com'
],
'bcc' => [
'jsmith@example.com'
],
'last_name' => '<string>',
'external_user_id' => 'crm-9f3a21',
'attachments' => [
123
],
'source_id' => '<string>',
'custom_attributes' => [
'order_id' => 'A-1024',
'plan' => 'pro'
],
'reuse_contact' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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/api/v1/conversations"
payload := strings.NewReader("{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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/api/v1/conversations")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/api/v1/conversations")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"id": 51,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "7d692b95-73dc-4f53-9343-6ed47a3db903",
"contact_id": 123,
"inbox_id": 123,
"closed_at": "2023-11-07T05:31:56Z",
"resolved_at": "2023-11-07T05:31:56Z",
"last_resolved_at": "2023-11-07T05:31:56Z",
"contact_last_seen_at": "2023-11-07T05:31:56Z",
"reference_number": "150",
"priority": "<string>",
"priority_id": 123,
"status": "Open",
"status_category": "open",
"status_id": 123,
"first_reply_at": "2023-11-07T05:31:56Z",
"last_reply_at": "2023-11-07T05:31:56Z",
"assigned_user_id": 123,
"assigned_team_id": 123,
"assignee": {
"id": 123,
"first_name": "<string>",
"last_name": "<string>",
"avatar_url": "<string>",
"type": "agent",
"availability_status": "online"
},
"waiting_since": "2023-11-07T05:31:56Z",
"snoozed_until": "2023-11-07T05:31:56Z",
"subject": "[GitHub] A third-party GitHub Application has been added",
"inbox_mail": "support@example.com",
"inbox_reply_to": "<string>",
"inbox_aliases": [
{
"email": "jsmith@example.com",
"verification_status": "not_verified",
"verified_at": "2023-11-07T05:31:56Z"
}
],
"inbox_name": "Support Inbox",
"inbox_channel": "email",
"tags": [
"<string>"
],
"meta": {},
"custom_attributes": {},
"last_message_at": "2023-11-07T05:31:56Z",
"last_message": "Hey! A third-party GitHub Application was recently authorized...",
"last_message_sender": "contact",
"last_interaction": "<string>",
"last_interaction_at": "2023-11-07T05:31:56Z",
"last_interaction_sender": "contact",
"contact": {
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"type": "contact",
"availability_status": "<string>",
"avatar_url": "<string>",
"phone_number": "<string>",
"phone_number_country_code": "<string>",
"country": "<string>",
"custom_attributes": {},
"enabled": true,
"last_active_at": "2023-11-07T05:31:56Z",
"last_login_at": "2023-11-07T05:31:56Z",
"external_user_id": "<string>"
},
"sla_policy_id": 123,
"sla_policy_name": "<string>",
"applied_sla_id": 123,
"next_sla_deadline_at": "2023-11-07T05:31:56Z",
"first_response_deadline_at": "2023-11-07T05:31:56Z",
"resolution_deadline_at": "2023-11-07T05:31:56Z",
"next_response_deadline_at": "2023-11-07T05:31:56Z",
"next_response_met_at": "2023-11-07T05:31:56Z",
"csat_rating": 123,
"csat_feedback": "<string>",
"csat_responded_at": "2023-11-07T05:31:56Z",
"previous_conversations": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "<string>",
"contact": {
"first_name": "<string>",
"last_name": "<string>",
"avatar_url": "<string>"
},
"last_message": "<string>",
"last_message_at": "2023-11-07T05:31:56Z",
"subject": "<string>"
}
]
}
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}Conversations
Create Conversation
Requires the conversations:write permission.
POST
/
api
/
v1
/
conversations
Create Conversation
curl --request POST \
--url http://localhost:8080/api/v1/conversations \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"content": "<string>",
"inbox_id": 123,
"contact_email": "jsmith@example.com",
"first_name": "<string>",
"subject": "<string>",
"send_from": "jsmith@example.com",
"team_id": 123,
"agent_id": 123,
"cc": [
"jsmith@example.com"
],
"bcc": [
"jsmith@example.com"
],
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [
123
],
"source_id": "<string>",
"custom_attributes": {
"order_id": "A-1024",
"plan": "pro"
},
"reuse_contact": false
}
'import requests
url = "http://localhost:8080/api/v1/conversations"
payload = {
"content": "<string>",
"inbox_id": 123,
"contact_email": "jsmith@example.com",
"first_name": "<string>",
"subject": "<string>",
"send_from": "jsmith@example.com",
"team_id": 123,
"agent_id": 123,
"cc": ["jsmith@example.com"],
"bcc": ["jsmith@example.com"],
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [123],
"source_id": "<string>",
"custom_attributes": {
"order_id": "A-1024",
"plan": "pro"
},
"reuse_contact": False
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
content: '<string>',
inbox_id: 123,
contact_email: 'jsmith@example.com',
first_name: '<string>',
subject: '<string>',
send_from: 'jsmith@example.com',
team_id: 123,
agent_id: 123,
cc: ['jsmith@example.com'],
bcc: ['jsmith@example.com'],
last_name: '<string>',
external_user_id: 'crm-9f3a21',
attachments: [123],
source_id: '<string>',
custom_attributes: {order_id: 'A-1024', plan: 'pro'},
reuse_contact: false
})
};
fetch('http://localhost:8080/api/v1/conversations', 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/api/v1/conversations",
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([
'content' => '<string>',
'inbox_id' => 123,
'contact_email' => 'jsmith@example.com',
'first_name' => '<string>',
'subject' => '<string>',
'send_from' => 'jsmith@example.com',
'team_id' => 123,
'agent_id' => 123,
'cc' => [
'jsmith@example.com'
],
'bcc' => [
'jsmith@example.com'
],
'last_name' => '<string>',
'external_user_id' => 'crm-9f3a21',
'attachments' => [
123
],
'source_id' => '<string>',
'custom_attributes' => [
'order_id' => 'A-1024',
'plan' => 'pro'
],
'reuse_contact' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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/api/v1/conversations"
payload := strings.NewReader("{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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/api/v1/conversations")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/api/v1/conversations")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"content\": \"<string>\",\n \"inbox_id\": 123,\n \"contact_email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"subject\": \"<string>\",\n \"send_from\": \"jsmith@example.com\",\n \"team_id\": 123,\n \"agent_id\": 123,\n \"cc\": [\n \"jsmith@example.com\"\n ],\n \"bcc\": [\n \"jsmith@example.com\"\n ],\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\n \"source_id\": \"<string>\",\n \"custom_attributes\": {\n \"order_id\": \"A-1024\",\n \"plan\": \"pro\"\n },\n \"reuse_contact\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"id": 51,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "7d692b95-73dc-4f53-9343-6ed47a3db903",
"contact_id": 123,
"inbox_id": 123,
"closed_at": "2023-11-07T05:31:56Z",
"resolved_at": "2023-11-07T05:31:56Z",
"last_resolved_at": "2023-11-07T05:31:56Z",
"contact_last_seen_at": "2023-11-07T05:31:56Z",
"reference_number": "150",
"priority": "<string>",
"priority_id": 123,
"status": "Open",
"status_category": "open",
"status_id": 123,
"first_reply_at": "2023-11-07T05:31:56Z",
"last_reply_at": "2023-11-07T05:31:56Z",
"assigned_user_id": 123,
"assigned_team_id": 123,
"assignee": {
"id": 123,
"first_name": "<string>",
"last_name": "<string>",
"avatar_url": "<string>",
"type": "agent",
"availability_status": "online"
},
"waiting_since": "2023-11-07T05:31:56Z",
"snoozed_until": "2023-11-07T05:31:56Z",
"subject": "[GitHub] A third-party GitHub Application has been added",
"inbox_mail": "support@example.com",
"inbox_reply_to": "<string>",
"inbox_aliases": [
{
"email": "jsmith@example.com",
"verification_status": "not_verified",
"verified_at": "2023-11-07T05:31:56Z"
}
],
"inbox_name": "Support Inbox",
"inbox_channel": "email",
"tags": [
"<string>"
],
"meta": {},
"custom_attributes": {},
"last_message_at": "2023-11-07T05:31:56Z",
"last_message": "Hey! A third-party GitHub Application was recently authorized...",
"last_message_sender": "contact",
"last_interaction": "<string>",
"last_interaction_at": "2023-11-07T05:31:56Z",
"last_interaction_sender": "contact",
"contact": {
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"type": "contact",
"availability_status": "<string>",
"avatar_url": "<string>",
"phone_number": "<string>",
"phone_number_country_code": "<string>",
"country": "<string>",
"custom_attributes": {},
"enabled": true,
"last_active_at": "2023-11-07T05:31:56Z",
"last_login_at": "2023-11-07T05:31:56Z",
"external_user_id": "<string>"
},
"sla_policy_id": 123,
"sla_policy_name": "<string>",
"applied_sla_id": 123,
"next_sla_deadline_at": "2023-11-07T05:31:56Z",
"first_response_deadline_at": "2023-11-07T05:31:56Z",
"resolution_deadline_at": "2023-11-07T05:31:56Z",
"next_response_deadline_at": "2023-11-07T05:31:56Z",
"next_response_met_at": "2023-11-07T05:31:56Z",
"csat_rating": 123,
"csat_feedback": "<string>",
"csat_responded_at": "2023-11-07T05:31:56Z",
"previous_conversations": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "<string>",
"contact": {
"first_name": "<string>",
"last_name": "<string>",
"avatar_url": "<string>"
},
"last_message": "<string>",
"last_message_at": "2023-11-07T05:31:56Z",
"subject": "<string>"
}
]
}
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}{
"status": "error",
"message": "Invalid request",
"data": "<unknown>",
"error_type": "GeneralException"
}Authorizations
basicAuthtokenAuth
Basic authentication using base64 encoded API key and secret. Format: Authorization: Basic <base64(api_key:api_secret)>
Body
application/json
Conversation creation details
Initial message content (Accepts HTML as well)
ID of an enabled email inbox for the conversation
Contact's email address
Contact's first name
Who initiated the conversation. 'contact' means the first message is treated as an incoming message from the contact; 'agent' means the first message is an outgoing reply from the agent. Automation rules are only evaluated for contact-initiated conversations (incoming messages); agent-initiated conversations skip automation rule evaluation.
Available options:
agent, contact Conversation subject
Agent-initiated only. Address to send the first message from: the inbox address or one of its verified aliases. Defaults to the inbox address.
Team ID to be assigned when conversation is created
Agent ID to be assigned when conversation is created
CC recipients of the first message
BCC recipients of the first message
Contact's last name
External identifier for the contact in your own system
Example:
"crm-9f3a21"
IDs of media uploaded by the caller with POST /api/v1/media. Media uploaded by another user is rejected with 403.
Contact-initiated only. RFC 5322 Message-ID of the original inbound email. It is stored on the first message so replies thread on it.
Custom attributes to set on the conversation. Keys that are not defined conversation custom attributes are ignored.
Example:
{ "order_id": "A-1024", "plan": "pro" }
When true, a matching existing contact is used as-is. When false and the caller has the contacts:write permission, the matched contact's name and email are updated and its external ID is filled in. Callers without contacts:write always reuse the contact as-is.
Was this page helpful?