Start an outbound conversation with a Contact as a given Agent
curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data @- <<EOF
{
"contact": {
"identifier": "+573001234567",
"identifierType": "PHONE",
"messageProviderType": "WHATSAPP",
"providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
},
"template": {
"name": "leadscout_outbound_fb_v1",
"orderedParams": [
"Maria",
"ACME"
],
"parameters": {
"recipient_first_name": "Maria",
"tracking_code": "TRK123"
},
"media": {
"type": "IMAGE",
"mediaId": null,
"url": null
}
},
"additionalMessages": [
{
"messageBody": "Just confirming we're still on for tomorrow at 10am.",
"mediaIds": []
}
],
"agentContext": {
"notes": "The Contact asked about pricing tiers last week.",
"mediaIds": []
},
"consent": {
"status": "GRANTED",
"capturedAt": "2026-04-20T10:00:00.000Z"
},
"handoffOverride": {
"preAssignedUser": {
"identifier": "advisor@acme.com",
"identifierType": "EMAIL"
}
},
"brandId": null,
"campaignId": null,
"forceSend": false
}
EOFimport requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound"
payload = {
"contact": {
"identifier": "+573001234567",
"identifierType": "PHONE",
"messageProviderType": "WHATSAPP",
"providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
},
"template": {
"name": "leadscout_outbound_fb_v1",
"orderedParams": ["Maria", "ACME"],
"parameters": {
"recipient_first_name": "Maria",
"tracking_code": "TRK123"
},
"media": {
"type": "IMAGE",
"mediaId": None,
"url": None
}
},
"additionalMessages": [
{
"messageBody": "Just confirming we're still on for tomorrow at 10am.",
"mediaIds": []
}
],
"agentContext": {
"notes": "The Contact asked about pricing tiers last week.",
"mediaIds": []
},
"consent": {
"status": "GRANTED",
"capturedAt": "2026-04-20T10:00:00.000Z"
},
"handoffOverride": { "preAssignedUser": {
"identifier": "advisor@acme.com",
"identifierType": "EMAIL"
} },
"brandId": None,
"campaignId": None,
"forceSend": False
}
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({
contact: {
identifier: '+573001234567',
identifierType: 'PHONE',
messageProviderType: 'WHATSAPP',
providerChannelId: 'c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c'
},
template: {
name: 'leadscout_outbound_fb_v1',
orderedParams: ['Maria', 'ACME'],
parameters: {recipient_first_name: 'Maria', tracking_code: 'TRK123'},
media: {type: 'IMAGE', mediaId: null, url: null}
},
additionalMessages: [
{
messageBody: 'Just confirming we\'re still on for tomorrow at 10am.',
mediaIds: []
}
],
agentContext: {notes: 'The Contact asked about pricing tiers last week.', mediaIds: []},
consent: {status: 'GRANTED', capturedAt: '2026-04-20T10:00:00.000Z'},
handoffOverride: {preAssignedUser: {identifier: 'advisor@acme.com', identifierType: 'EMAIL'}},
brandId: null,
campaignId: null,
forceSend: false
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound', 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}/agents/{agentId}/outbound",
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([
'contact' => [
'identifier' => '+573001234567',
'identifierType' => 'PHONE',
'messageProviderType' => 'WHATSAPP',
'providerChannelId' => 'c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c'
],
'template' => [
'name' => 'leadscout_outbound_fb_v1',
'orderedParams' => [
'Maria',
'ACME'
],
'parameters' => [
'recipient_first_name' => 'Maria',
'tracking_code' => 'TRK123'
],
'media' => [
'type' => 'IMAGE',
'mediaId' => null,
'url' => null
]
],
'additionalMessages' => [
[
'messageBody' => 'Just confirming we\'re still on for tomorrow at 10am.',
'mediaIds' => [
]
]
],
'agentContext' => [
'notes' => 'The Contact asked about pricing tiers last week.',
'mediaIds' => [
]
],
'consent' => [
'status' => 'GRANTED',
'capturedAt' => '2026-04-20T10:00:00.000Z'
],
'handoffOverride' => [
'preAssignedUser' => [
'identifier' => 'advisor@acme.com',
'identifierType' => 'EMAIL'
]
],
'brandId' => null,
'campaignId' => null,
'forceSend' => false
]),
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}/agents/{agentId}/outbound"
payload := strings.NewReader("{\n \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\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}/agents/{agentId}/outbound")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound")
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 \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\n}"
response = http.request(request)
puts response.read_body{
"conversation": {
"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"
},
"contact": {
"id": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"workspaceId": "92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5",
"type": "NORMAL",
"createdAt": "2003-04-10T08:00:00.000Z",
"updatedAt": "2003-04-10T08:00:00.000Z",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"cellphone": "+14084029292",
"customAttributes": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"languageCode": "EN",
"ownerId": "37673840-6259-40f9-bbe5-a7db40f8e3cf"
},
"templateSent": {
"name": "leadscout_outbound_fb_v1",
"messageId": "7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f"
},
"additionalMessagesPersisted": 0,
"alreadyInitiated": false,
"recovered": false
}Agents API
Start an outbound conversation with a Contact as a given Agent
Start an outbound conversation with a known Contact, answered by the given Agent.
Works for LeadScout and Service Agents. The Contact is resolved first, then the Agent, which must exist in
the workspace and be available (see GET /agents). The template must exist and be APPROVED, and a
handoffOverride Bridge User must be valid. If template.media.mediaId is unknown, the request fails
with 400 BRIDGE_AI_LEADSCOUT_0016 only after the conversation was created or recovered, so a retry after
that error may answer differently. Body rules (consent.status=GRANTED without capturedAt, template.media
without exactly one of mediaId or url) fail with 400 BRIDGE_CORE_0103.
The conversation opens on one of the Agent’s active WhatsApp lines, controlled by the Agent, with the template as its first message. A line is picked in this order:
- A free line.
- Otherwise, a line holding a released conversation with this Contact that can be recovered. Recovering
returns
recovered=trueand replaces the previous outbound context andagentContext. This happens even withforceSend=false. - Otherwise, when no line is free or recoverable:
forceSend=false(default) fails with 409BRIDGE_AI_LEADSCOUT_0008;forceSend=truereuses a line occupied by an active conversation with this Contact, preferring one this Agent controls. If the chosen conversation is held by another Agent or a Bridge User, the call fails with 409BRIDGE_AI_AGENT_OUTBOUND_0006and nothing is written. Release it first, then retry. Lines whose conversation is blocked or was released without recovery are never used, so if no line is occupied by an active conversation the call fails with 409BRIDGE_AI_LEADSCOUT_0008even withforceSend=true.
contact.providerChannelId is a preference: the pinned line is used when it is free or recoverable;
otherwise the same order applies over all the Agent’s lines. Among occupied lines, one this Agent controls
comes first; if none does, the pinned line is the one reused (and may fail with 0006).
Reusing a conversation depends on the Agent type:
- LeadScout: if its LeadScout session is still open and not expired, the call fails with 409
BRIDGE_AI_LEADSCOUT_0017(extracarriesconversationId,sessionIdandstage). If an expired session cannot be finalized, it fails with 409BRIDGE_AI_LEADSCOUT_0018. - Service Agent: an open, unexpired service session is continued; an expired one is closed as abandoned and a new one opens.
POST
/
bridge
/
api
/
v1
/
workspaces
/
{workspaceId}
/
agents
/
{agentId}
/
outbound
Start an outbound conversation with a Contact as a given Agent
curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data @- <<EOF
{
"contact": {
"identifier": "+573001234567",
"identifierType": "PHONE",
"messageProviderType": "WHATSAPP",
"providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
},
"template": {
"name": "leadscout_outbound_fb_v1",
"orderedParams": [
"Maria",
"ACME"
],
"parameters": {
"recipient_first_name": "Maria",
"tracking_code": "TRK123"
},
"media": {
"type": "IMAGE",
"mediaId": null,
"url": null
}
},
"additionalMessages": [
{
"messageBody": "Just confirming we're still on for tomorrow at 10am.",
"mediaIds": []
}
],
"agentContext": {
"notes": "The Contact asked about pricing tiers last week.",
"mediaIds": []
},
"consent": {
"status": "GRANTED",
"capturedAt": "2026-04-20T10:00:00.000Z"
},
"handoffOverride": {
"preAssignedUser": {
"identifier": "advisor@acme.com",
"identifierType": "EMAIL"
}
},
"brandId": null,
"campaignId": null,
"forceSend": false
}
EOFimport requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound"
payload = {
"contact": {
"identifier": "+573001234567",
"identifierType": "PHONE",
"messageProviderType": "WHATSAPP",
"providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
},
"template": {
"name": "leadscout_outbound_fb_v1",
"orderedParams": ["Maria", "ACME"],
"parameters": {
"recipient_first_name": "Maria",
"tracking_code": "TRK123"
},
"media": {
"type": "IMAGE",
"mediaId": None,
"url": None
}
},
"additionalMessages": [
{
"messageBody": "Just confirming we're still on for tomorrow at 10am.",
"mediaIds": []
}
],
"agentContext": {
"notes": "The Contact asked about pricing tiers last week.",
"mediaIds": []
},
"consent": {
"status": "GRANTED",
"capturedAt": "2026-04-20T10:00:00.000Z"
},
"handoffOverride": { "preAssignedUser": {
"identifier": "advisor@acme.com",
"identifierType": "EMAIL"
} },
"brandId": None,
"campaignId": None,
"forceSend": False
}
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({
contact: {
identifier: '+573001234567',
identifierType: 'PHONE',
messageProviderType: 'WHATSAPP',
providerChannelId: 'c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c'
},
template: {
name: 'leadscout_outbound_fb_v1',
orderedParams: ['Maria', 'ACME'],
parameters: {recipient_first_name: 'Maria', tracking_code: 'TRK123'},
media: {type: 'IMAGE', mediaId: null, url: null}
},
additionalMessages: [
{
messageBody: 'Just confirming we\'re still on for tomorrow at 10am.',
mediaIds: []
}
],
agentContext: {notes: 'The Contact asked about pricing tiers last week.', mediaIds: []},
consent: {status: 'GRANTED', capturedAt: '2026-04-20T10:00:00.000Z'},
handoffOverride: {preAssignedUser: {identifier: 'advisor@acme.com', identifierType: 'EMAIL'}},
brandId: null,
campaignId: null,
forceSend: false
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound', 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}/agents/{agentId}/outbound",
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([
'contact' => [
'identifier' => '+573001234567',
'identifierType' => 'PHONE',
'messageProviderType' => 'WHATSAPP',
'providerChannelId' => 'c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c'
],
'template' => [
'name' => 'leadscout_outbound_fb_v1',
'orderedParams' => [
'Maria',
'ACME'
],
'parameters' => [
'recipient_first_name' => 'Maria',
'tracking_code' => 'TRK123'
],
'media' => [
'type' => 'IMAGE',
'mediaId' => null,
'url' => null
]
],
'additionalMessages' => [
[
'messageBody' => 'Just confirming we\'re still on for tomorrow at 10am.',
'mediaIds' => [
]
]
],
'agentContext' => [
'notes' => 'The Contact asked about pricing tiers last week.',
'mediaIds' => [
]
],
'consent' => [
'status' => 'GRANTED',
'capturedAt' => '2026-04-20T10:00:00.000Z'
],
'handoffOverride' => [
'preAssignedUser' => [
'identifier' => 'advisor@acme.com',
'identifierType' => 'EMAIL'
]
],
'brandId' => null,
'campaignId' => null,
'forceSend' => false
]),
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}/agents/{agentId}/outbound"
payload := strings.NewReader("{\n \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\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}/agents/{agentId}/outbound")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound")
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 \"contact\": {\n \"identifier\": \"+573001234567\",\n \"identifierType\": \"PHONE\",\n \"messageProviderType\": \"WHATSAPP\",\n \"providerChannelId\": \"c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c\"\n },\n \"template\": {\n \"name\": \"leadscout_outbound_fb_v1\",\n \"orderedParams\": [\n \"Maria\",\n \"ACME\"\n ],\n \"parameters\": {\n \"recipient_first_name\": \"Maria\",\n \"tracking_code\": \"TRK123\"\n },\n \"media\": {\n \"type\": \"IMAGE\",\n \"mediaId\": null,\n \"url\": null\n }\n },\n \"additionalMessages\": [\n {\n \"messageBody\": \"Just confirming we're still on for tomorrow at 10am.\",\n \"mediaIds\": []\n }\n ],\n \"agentContext\": {\n \"notes\": \"The Contact asked about pricing tiers last week.\",\n \"mediaIds\": []\n },\n \"consent\": {\n \"status\": \"GRANTED\",\n \"capturedAt\": \"2026-04-20T10:00:00.000Z\"\n },\n \"handoffOverride\": {\n \"preAssignedUser\": {\n \"identifier\": \"advisor@acme.com\",\n \"identifierType\": \"EMAIL\"\n }\n },\n \"brandId\": null,\n \"campaignId\": null,\n \"forceSend\": false\n}"
response = http.request(request)
puts response.read_body{
"conversation": {
"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"
},
"contact": {
"id": "b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234",
"workspaceId": "92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5",
"type": "NORMAL",
"createdAt": "2003-04-10T08:00:00.000Z",
"updatedAt": "2003-04-10T08:00:00.000Z",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"cellphone": "+14084029292",
"customAttributes": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"languageCode": "EN",
"ownerId": "37673840-6259-40f9-bbe5-a7db40f8e3cf"
},
"templateSent": {
"name": "leadscout_outbound_fb_v1",
"messageId": "7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f"
},
"additionalMessagesPersisted": 0,
"alreadyInitiated": false,
"recovered": false
}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"
Unique identifier of the Agent (UUID v4), as listed by GET /agents.
Example:
"4e362e2b-67b2-4a7e-a9df-e9ecf9141be8"
Body
application/json
Request body for starting an outbound conversation answered by a given Agent.
The Contact this outbound conversation targets. Must already exist in the workspace.
Show child attributes
Show child attributes
The opening template to send.
Show child attributes
Show child attributes
Up to five text follow-ups stored on the conversation right after the opening template, in the order given, and sent like the template. Attachments (mediaIds) are not sent yet.
Maximum array length:
5Show child attributes
Show child attributes
Notes and media stored on the conversation as context for the Agent and for Bridge Users.
Show child attributes
Show child attributes
Tenant-affirmed opt-in evidence recorded verbatim on the conversation.
Show child attributes
Show child attributes
Pre-assigns the Bridge User who receives the handoff of the outbound conversation.
Show child attributes
Show child attributes
Optional brand id. When given, only the Agent's lines linked to this brand are eligible; if none is, the request fails with 404. Omit to consider every line of the Agent.
Example:
null
Optional campaign reference stored on the conversation for audit and reporting.
Example:
null
Controls what happens when no line of the Agent is free or recoverable. A free line always wins, then a line holding a released conversation with this Contact that can be recovered, whatever this flag says. When neither exists: with false (default) the request fails with 409 BRIDGE_AI_LEADSCOUT_0008; with true, a line occupied by an active conversation with this Contact is reused, preferring one this Agent controls. If the chosen conversation is held by another Agent or a Bridge User the request fails with 409 BRIDGE_AI_AGENT_OUTBOUND_0006 and nothing is written; release it first, then retry. Lines whose conversation is blocked or was released without recovery are never used, so with no line occupied by an active conversation the request fails with 409 BRIDGE_AI_LEADSCOUT_0008 even with true.
Examples:
false
true
Response
Successful Response
Response body for a successful Agent outbound initiation.
The conversation the Agent now controls: newly created, reused (alreadyInitiated) or recovered (recovered).
Show child attributes
Show child attributes
The contact the conversation was initiated with.
Show child attributes
Show child attributes
Summary of the template stored to open the conversation.
Show child attributes
Show child attributes
Count of follow-up messages persisted on the conversation.
Examples:
0
3
True when this request landed on a pre-existing conversation (forceSend=true reuse path); false when a fresh conversation was created. Informational only — the new template and follow-ups are persisted either way.
Examples:
false
true
True when a released conversation the Contact had on the line was recovered instead of creating a new one. Recovery replaces the previous outbound context and agentContext. Recoverable lines are used even with forceSend=false.
Examples:
false
true
Was this page helpful?