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>",
"team_id": 123,
"agent_id": 123,
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [
123
],
"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>",
"team_id": 123,
"agent_id": 123,
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [123],
"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>',
team_id: 123,
agent_id: 123,
last_name: '<string>',
external_user_id: 'crm-9f3a21',
attachments: [123],
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>',
'team_id' => 123,
'agent_id' => 123,
'last_name' => '<string>',
'external_user_id' => 'crm-9f3a21',
'attachments' => [
123
],
'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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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",
"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,
"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_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>",
"team_id": 123,
"agent_id": 123,
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [
123
],
"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>",
"team_id": 123,
"agent_id": 123,
"last_name": "<string>",
"external_user_id": "crm-9f3a21",
"attachments": [123],
"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>',
team_id: 123,
agent_id: 123,
last_name: '<string>',
external_user_id: 'crm-9f3a21',
attachments: [123],
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>',
'team_id' => 123,
'agent_id' => 123,
'last_name' => '<string>',
'external_user_id' => 'crm-9f3a21',
'attachments' => [
123
],
'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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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 \"team_id\": 123,\n \"agent_id\": 123,\n \"last_name\": \"<string>\",\n \"external_user_id\": \"crm-9f3a21\",\n \"attachments\": [\n 123\n ],\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",
"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,
"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_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
Team ID to be assigned when conversation is created
Agent ID to be assigned when conversation is created
Contact's last name
External identifier for the contact in your own system
Example:
"crm-9f3a21"
Array of attachment IDs
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?