Creates a new conversation with flexible user identification.
curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"participants": {
"externals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL",
"messageProviderType": "WHATSAPP",
"providerChannelId": "<string>",
"brandId": "<string>"
}
],
"internals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL"
}
]
},
"name": "Bridge Support Team",
"status": "ACTIVE",
"teamId": "9fd1468d-e5ca-4ba3-98d1-13017e6f3808",
"onboardingTemplates": [
{
"templateId": "4061e74e-f6fe-4072-a760-3aec0b64f7a6",
"parameters": {
"delivery_date": "3 de octubre",
"order_number": "A-10492"
}
}
]
}
'import requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations"
payload = {
"participants": {
"externals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL",
"messageProviderType": "WHATSAPP",
"providerChannelId": "<string>",
"brandId": "<string>"
}
],
"internals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL"
}
]
},
"name": "Bridge Support Team",
"status": "ACTIVE",
"teamId": "9fd1468d-e5ca-4ba3-98d1-13017e6f3808",
"onboardingTemplates": [
{
"templateId": "4061e74e-f6fe-4072-a760-3aec0b64f7a6",
"parameters": {
"delivery_date": "3 de octubre",
"order_number": "A-10492"
}
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
participants: {
externals: [
{
identifier: 'john.doe@example.com',
identifierType: 'EMAIL',
messageProviderType: 'WHATSAPP',
providerChannelId: '<string>',
brandId: '<string>'
}
],
internals: [{identifier: 'john.doe@example.com', identifierType: 'EMAIL'}]
},
name: 'Bridge Support Team',
status: 'ACTIVE',
teamId: '9fd1468d-e5ca-4ba3-98d1-13017e6f3808',
onboardingTemplates: [
{
templateId: '4061e74e-f6fe-4072-a760-3aec0b64f7a6',
parameters: {delivery_date: '3 de octubre', order_number: 'A-10492'}
}
]
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/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_URL => "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/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([
'participants' => [
'externals' => [
[
'identifier' => 'john.doe@example.com',
'identifierType' => 'EMAIL',
'messageProviderType' => 'WHATSAPP',
'providerChannelId' => '<string>',
'brandId' => '<string>'
]
],
'internals' => [
[
'identifier' => 'john.doe@example.com',
'identifierType' => 'EMAIL'
]
]
],
'name' => 'Bridge Support Team',
'status' => 'ACTIVE',
'teamId' => '9fd1468d-e5ca-4ba3-98d1-13017e6f3808',
'onboardingTemplates' => [
[
'templateId' => '4061e74e-f6fe-4072-a760-3aec0b64f7a6',
'parameters' => [
'delivery_date' => '3 de octubre',
'order_number' => 'A-10492'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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 := "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations"
payload := strings.NewReader("{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"workspaceId": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"participants": {
"externals": [
{
"identifier": "ef7ee722-5f95-415a-9a98-81eeae178b11",
"identifierType": "EMAIL",
"role": "EXTERNAL",
"joinedAt": "2004-04-10T09:00:00.000Z",
"lastSeenAt": null
}
],
"internals": [
{
"identifier": "ef7ee722-5f95-415a-9a98-81eeae178b11",
"identifierType": "EMAIL",
"role": "EXTERNAL",
"joinedAt": "2004-04-10T09:00:00.000Z",
"lastSeenAt": null
}
]
},
"createdAt": "2003-04-10T09:00:00.000Z",
"updatedAt": "2003-04-10T09:00:00.000Z",
"name": "Bridge Support Team",
"status": "ACTIVE"
}Conversations API
Creates a new conversation with flexible user identification.
Create a new conversation with flexible user identification.
External users can be identified by ID, email, or phone. Internal users are only assigned when explicitly specified; otherwise, conversations are auto-assigned by round-robin through a team or left open for any available internal user.
POST
/
bridge
/
api
/
v1
/
workspaces
/
{workspaceId}
/
conversations
Creates a new conversation with flexible user identification.
curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"participants": {
"externals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL",
"messageProviderType": "WHATSAPP",
"providerChannelId": "<string>",
"brandId": "<string>"
}
],
"internals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL"
}
]
},
"name": "Bridge Support Team",
"status": "ACTIVE",
"teamId": "9fd1468d-e5ca-4ba3-98d1-13017e6f3808",
"onboardingTemplates": [
{
"templateId": "4061e74e-f6fe-4072-a760-3aec0b64f7a6",
"parameters": {
"delivery_date": "3 de octubre",
"order_number": "A-10492"
}
}
]
}
'import requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations"
payload = {
"participants": {
"externals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL",
"messageProviderType": "WHATSAPP",
"providerChannelId": "<string>",
"brandId": "<string>"
}
],
"internals": [
{
"identifier": "john.doe@example.com",
"identifierType": "EMAIL"
}
]
},
"name": "Bridge Support Team",
"status": "ACTIVE",
"teamId": "9fd1468d-e5ca-4ba3-98d1-13017e6f3808",
"onboardingTemplates": [
{
"templateId": "4061e74e-f6fe-4072-a760-3aec0b64f7a6",
"parameters": {
"delivery_date": "3 de octubre",
"order_number": "A-10492"
}
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
participants: {
externals: [
{
identifier: 'john.doe@example.com',
identifierType: 'EMAIL',
messageProviderType: 'WHATSAPP',
providerChannelId: '<string>',
brandId: '<string>'
}
],
internals: [{identifier: 'john.doe@example.com', identifierType: 'EMAIL'}]
},
name: 'Bridge Support Team',
status: 'ACTIVE',
teamId: '9fd1468d-e5ca-4ba3-98d1-13017e6f3808',
onboardingTemplates: [
{
templateId: '4061e74e-f6fe-4072-a760-3aec0b64f7a6',
parameters: {delivery_date: '3 de octubre', order_number: 'A-10492'}
}
]
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/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_URL => "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/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([
'participants' => [
'externals' => [
[
'identifier' => 'john.doe@example.com',
'identifierType' => 'EMAIL',
'messageProviderType' => 'WHATSAPP',
'providerChannelId' => '<string>',
'brandId' => '<string>'
]
],
'internals' => [
[
'identifier' => 'john.doe@example.com',
'identifierType' => 'EMAIL'
]
]
],
'name' => 'Bridge Support Team',
'status' => 'ACTIVE',
'teamId' => '9fd1468d-e5ca-4ba3-98d1-13017e6f3808',
'onboardingTemplates' => [
[
'templateId' => '4061e74e-f6fe-4072-a760-3aec0b64f7a6',
'parameters' => [
'delivery_date' => '3 de octubre',
'order_number' => 'A-10492'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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 := "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations"
payload := strings.NewReader("{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"participants\": {\n \"externals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"<string>\",\n \"brandId\": \"<string>\"\n }\n ],\n \"internals\": [\n {\n \"identifier\": \"john.doe@example.com\",\n \"identifierType\": \"EMAIL\"\n }\n ]\n },\n \"name\": \"Bridge Support Team\",\n \"status\": \"ACTIVE\",\n \"teamId\": \"9fd1468d-e5ca-4ba3-98d1-13017e6f3808\",\n \"onboardingTemplates\": [\n {\n \"templateId\": \"4061e74e-f6fe-4072-a760-3aec0b64f7a6\",\n \"parameters\": {\n \"delivery_date\": \"3 de octubre\",\n \"order_number\": \"A-10492\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"workspaceId": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"participants": {
"externals": [
{
"identifier": "ef7ee722-5f95-415a-9a98-81eeae178b11",
"identifierType": "EMAIL",
"role": "EXTERNAL",
"joinedAt": "2004-04-10T09:00:00.000Z",
"lastSeenAt": null
}
],
"internals": [
{
"identifier": "ef7ee722-5f95-415a-9a98-81eeae178b11",
"identifierType": "EMAIL",
"role": "EXTERNAL",
"joinedAt": "2004-04-10T09:00:00.000Z",
"lastSeenAt": null
}
]
},
"createdAt": "2003-04-10T09:00:00.000Z",
"updatedAt": "2003-04-10T09:00:00.000Z",
"name": "Bridge Support Team",
"status": "ACTIVE"
}Authorizations
Copy the API key as provided by the Bridge Console.
Path Parameters
Unique identifier of the workspace (UUID v4).
Example:
"b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234"
Body
application/json
Request body for creating a new conversation.
Participants to add to conversation.
Show child attributes
Show child attributes
Optional name/title for the conversation.
Example:
"Bridge Support Team"
Initial conversation status - 'active' for visible conversations, 'ghost' for invisible until first interaction.
Available options:
ACTIVE, GHOST, RELEASED, NOT_ASSIGNED_TO_HUMAN, BLOCKED Example:
"ACTIVE"
Team UUID for round-robin assignment (optional, mutually exclusive with internalParticipants).
Example:
"9fd1468d-e5ca-4ba3-98d1-13017e6f3808"
Ordered templates to open the conversation with. They replace the workspace's configured onboarding sequence for this conversation, either entirely or only its first template, depending on how the workspace is set up; in the second case the rest of the configured sequence is still sent after yours. Position implies order. Omit to keep the workspace default. Each template must exist, belong to your workspace or the platform scope, and — for WhatsApp provider templates — be approved by Meta for the WhatsApp Business Account behind the line each participant is reached on; otherwise the request is rejected and no conversation is created. A template whose variables need values only you can provide takes them in the entry's parameters. If one of the configured templates sent after yours needs values only the caller can provide, the request is rejected with 422 BRIDGE_CONVERSATION_0608, with extra.templateId naming that template and extra.origin set to WORKSPACE_CONFIGURATION. Changing the request will not help: ask a workspace admin to change the onboarding sequence.
Show child attributes
Show child attributes
Response
Successful Response
Response body for conversation details.
Unique identifier of the conversation (UUID v4).
Example:
"b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234"
Unique identifier of the workspace (UUID v4).
Example:
"b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234"
Participants of the conversation.
Show child attributes
Show child attributes
Timestamp when the conversation was created.
Example:
"2003-04-10T09:00:00.000Z"
Timestamp when the conversation was last updated.
Example:
"2003-04-10T09:00:00.000Z"
Optional name/title for the conversation.
Example:
"Bridge Support Team"
Current conversation status - 'ACTIVE' for visible conversations, 'GHOST' for invisible until first interaction.
Available options:
ACTIVE, GHOST, RELEASED, NOT_ASSIGNED_TO_HUMAN, BLOCKED Example:
"ACTIVE"
Was this page helpful?