> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridge.new/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bridge exposes three integration surfaces: the REST Integrations API for pushing data into Bridge, webhooks for receiving events from Bridge, and the public Custom Connections endpoint that a tenant's landing page posts to.
> The Integrations API host is https://api-connect-us.bridge.new and every request to it must be authenticated with the x-api-key header. Bridge does not use bearer tokens or OAuth.
> The Custom Connections endpoint is different and the Integrations API rules do not apply to it: it has its own host, it takes no x-api-key and no authentication header of any kind, and it is called from a visitor's browser. It is identified by a workspace id and a capture key together with a reCAPTCHA token. Never tell a reader to authenticate it with an API key, and never tell them to keep its capture key out of frontend code - it is designed to live in the page.
> REST error catalog keys use BRIDGE_<DOMAIN>_<NNNN>, for example BRIDGE_CONVERSATION_0001. Some reviewed legacy handlers return a recognized code plus a symbolic suffix separated by |; preserve the complete received value and use the compatible catalog lookup on /error-codes. Custom Connections uses separate BRIDGE.CAMPAIGN_LEADS.<NAME> identifiers on its own error reference. Never invent an error code or confuse the two integration surfaces.
> This documentation covers the Integrations API, webhooks and Custom Connections only. It does not describe the Bridge web application or its internal APIs.
> Before generating an API request, read the relevant OpenAPI specification or the individual endpoint Markdown page. llms-full.txt collects guides and endpoint descriptions; it does not embed every request and response schema. The REST and Custom Connections contracts are separate.
> Preserve the published host, method, path, operationId, authentication, headers, parameter and field names, types, formats, required and nullable fields, enums, defaults, limits, and response codes. Do not invent identifiers, fields, retry rules, or delivery guarantees. When published sources conflict, identify the conflicting passages and ask Bridge support to confirm the current behavior before relying on it.
> Custom Connections is the current name of the landing-page feature previously documented as Lead Capture. The existing /lead-capture documentation URLs, captureKey field, campaign-leads endpoint, and BRIDGE.CAMPAIGN_LEADS error identifiers are unchanged. This is a naming change, not a change to authentication or the API contract.
> For a complete workflow, start with the task guides: /guides/first-conversation, /guides/send-attachments, /guides/send-template, /guides/agent-outbound, /guides/pagination, /guides/identifiers and /guides/responses. Read the endpoint contract as well as the recipe. Outbound requires an existing Contact, but does not require creating a separate Conversation first.
> forceSend=true permits reuse of an existing active conversation; it does not create a fresh one by ignoring it and it is not idempotency. Recovery of a released recoverable conversation can occur even with false. The LeadScout and Agents outbound routes have different line-selection and controller checks; use /guides/agent-outbound.
> For webhook HMAC, follow /webhooks/verifying-signatures exactly: the Python JSON serialization with sorted keys is signed; X-Bridge-Timestamp is not included in that signature. Do not claim a signed timestamp, raw-body signing, exactly-once delivery or a global event order. Use /webhooks/receive-events for durable acceptance and duplicates.
> A 201 message response, 202 handoff or 202 Custom Connections response is not a provider delivery receipt. Do not invent a polling endpoint from messageId, trackingId or requestId. REST validation parsing must tolerate the compatibility difference explained in /error-codes.
> The documentation is available in English (existing root URLs), Spanish (/es/) and Brazilian Portuguese (/pt-br/). Prefer the reader's language when a localized page exists, but preserve the API's exact field names, enums, routes, authentication and examples. Translations describe the same API; they do not introduce regional API hosts or behaviors.
> For coding-assistant setup, use /connect-your-agent, /es/connect-your-agent or /pt-br/connect-your-agent. The Bridge documentation MCP server reads published documentation and has a separate optional feedback tool. Connecting it does not connect the coding assistant to a customer workspace or authorize live business requests.
> For direct HTTP access without MCP, start at https://docs.bridge.new/llms.txt. It lists every published page in English, Spanish and Brazilian Portuguese. Choose /llms-en.json, /llms-es.json or /llms-pt-br.json for a language-specific index, and /llms-full-en.json, /llms-full-es.json or /llms-full-pt-br.json for collected content. /llms-full.txt contains the combined collection. Fetch the original OpenAPI specification for exact schemas.
> For HTTP page reads, follow the .md URLs from the index or request Accept: text/markdown at the canonical page URL. The MCP virtual filesystem uses .mdx page paths instead; .mdx is not the public HTTP export extension. With Search MCP, set language to en, es or pt-BR explicitly; its default is en.
> For integration capabilities and source-selection rules, read https://docs.bridge.new/skill.md. Documentation access does not authorize business API actions; use the actual user request, workspace, credentials and target identifiers for any live integration.

# Start an Agent outbound conversation

> Choose an Agent, send an opening template, understand forceSend and recovery, and request a LeadScout handoff.

Use outbound when an existing Contact should receive an approved WhatsApp template and continue with an AI Agent. Use [create a conversation](https://docs.bridge.new/guides/first-conversation.md) for the general conversation workflow.

## Choose the operation

| Your goal | Operation | How the Agent is selected |
| - | - | - |
| Start with a specific LeadScout or Service Agent | `POST /bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound` | You supply the Agent ID from `GET /agents`. |
| Start with a LeadScout selected through the workspace's eligible lines | `POST /bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound` | Bridge resolves the prospecting Agent for the line. |

Both use the REST API host `https://api-connect-us.bridge.new` and a server-side `x-api-key`. They have separate request schemas. Read the [Agents outbound reference](https://docs.bridge.new/api-reference/agents-api/start-an-outbound-conversation-with-a-contact-as-a-given-agent.md) or [LeadScout outbound reference](https://docs.bridge.new/api-reference/leadscout-api/initiate-a-leadscout-outbound-conversation-with-a-known-lead.md) for the operation you use.

## Before you send

1. [Look up the Contact](https://docs.bridge.new/api-reference/contacts-api/retrieve-a-contact-by-an-identifier.md), or [create it](https://docs.bridge.new/api-reference/contacts-api/create-a-new-contact.md) if missing. Outbound requires a Contact that already exists in the workspace; you do not need to create a separate Conversation or Message first.
2. [List Agents](https://docs.bridge.new/api-reference/agents-api/list-the-agents-of-a-workspace.md). Choose an available Agent and read its `lines[].providerChannelId`. An AI Agent ID differs from a human Bridge User ID.
3. Choose an approved template. [Discover its variables](https://docs.bridge.new/guides/send-template.md#1-discover-the-variables), supply caller-required values, and check that it is approved for the destination line. Use only the discovery step as this prerequisite; the separate Conversation-creation step in that recipe is not needed for outbound.
4. Confirm that your business has the required opt-in. If you send `consent.status: "GRANTED"`, include `capturedAt`; this records your assertion of consent.

For Agents outbound, `contact.providerChannelId` must belong to the chosen Agent when supplied. It is a preference: another eligible Agent line can be selected. For LeadScout outbound, an explicit line is respected. [Identifiers and their sources](https://docs.bridge.new/guides/identifiers.md) explains which values to use.

## Send a minimal Agent request

Replace every placeholder. This example assumes the chosen template has no unresolved caller-required variables. Set `forceSend` deliberately; the example keeps the default behavior explicit.

```bash theme={null}
curl --fail-with-body --request POST \
  "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/outbound" \
  --header "x-api-key: $BRIDGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "identifier": "f0000001-0000-4000-8000-000000000001",
      "identifierType": "ID",
      "messageProviderType": "WHATSAPP"
    },
    "template": {
      "id": "f0000040-0000-4000-8000-000000000040"
    },
    "forceSend": false
  }'
```

A successful request returns `201`. Store `conversation.id` and interpret these response fields:

| Field | Meaning |
| - | - |
| `alreadyInitiated: true` | An existing active conversation was reused. The successful request still adds its new template and follow-ups. |
| `recovered: true` | A released, recoverable conversation was recovered, retaining its ID. Its previous outbound context and `agentContext` are replaced. |
| `additionalMessagesPersisted` | The number of follow-up messages stored. This is not a delivery receipt. |
| `templateSent` | A summary of the opening template stored for sending. Do not interpret the field name as proof of recipient delivery. |

New creation has neither reuse nor recovery set to true. Recovery can happen with `forceSend: false`. Additional messages are persisted in request order; do not rely on a promise that they wait for the Contact to reply. The shared outbound flow persists text follow-ups and does not attach their `mediaIds`. Use the documented `template.media` option for media on the opening template, or the [Message attachment workflow](https://docs.bridge.new/guides/send-attachments.md) for a separate message.

## What forceSend does

Availability is evaluated for **this Contact's conversation on each line**. An occupied line here does not mean the corporate WhatsApp line is globally reserved for one Contact.

The following rules remain subject to Agent availability, template validation, consent validation and session checks.

On a narrow screen, scroll horizontally to compare all four choices. Keyboard users can focus this comparison and use the arrow keys.

| Situation | LeadScout: false | LeadScout: true | Agents: false | Agents: true |
| - | - | - | - | - |
| Selected line is free | Create | Create | Create | Create |
| Selected line holds a released conversation marked recoverable | Recover the same ID | Recover the same ID | Recover the same ID | Recover the same ID |
| Automatic selection finds only occupied, active conversations | `409 …0008` | Reuse the first eligible occupied conversation | `409 …0008` | Prefer one controlled by the requested Agent, then apply the controller check below |
| Explicit line is occupied | `409 …0007` | Reuse that conversation | Try other free or recoverable Agent lines; otherwise `409 …0008` | Try other free or recoverable Agent lines; otherwise prefer an occupied line the Agent controls |
| Selected occupied conversation is controlled by a human or another Agent | No active reuse | Legacy route permits reuse, subject to other checks; this does not itself promise a controller transfer | No active reuse | `409 BRIDGE_AI_AGENT_OUTBOUND_0006`; this rejection writes nothing |
| Only blocked or released, nonrecoverable conversations are available | `409 …0008` | `409 …0008` | `409 …0008` | `409 …0008` |

In this table, `…0007` is `BRIDGE_AI_LEADSCOUT_0007` and `…0008` is `BRIDGE_AI_LEADSCOUT_0008`. A released conversation is recoverable only when its stored recovery flag permits it; `forceSend` does not make it recoverable.

For both routes, a LeadScout session that is still open and unexpired blocks a new outbound request with `409 BRIDGE_AI_LEADSCOUT_0017`. Failure to finalize an expired session returns `409 BRIDGE_AI_LEADSCOUT_0018`. A Service Agent can continue its open, unexpired service session; an expired session is closed before a new one opens.

> [!WARNING]
>
> `forceSend` is not an idempotency key. Repeating a successful request can add another template and more messages. It does not bypass blocked conversations, session checks, approval rules or validation. A timeout leaves the outcome uncertain: inspect the conversation before deciding whether to submit again.

## Handle conflicts and partial work

| Result | Next step |
| - | - |
| `BRIDGE_AI_LEADSCOUT_0007` / `0008` | Check the Contact's existing conversation and eligible lines. Decide whether reuse is appropriate before enabling `forceSend`. |
| `BRIDGE_AI_AGENT_OUTBOUND_0006` | Inspect `extra.conversationId` and its controller. Coordinate ownership before deliberately releasing it. Do not automatically interrupt a human conversation. |
| `BRIDGE_AI_LEADSCOUT_0017` / `0018` | Resolve the existing session or contact support. Switching `forceSend` to true does not fix the session. |
| `BRIDGE_AI_LEADSCOUT_0019` / `0020` / `0021` | Correct missing, conflicting or unknown template variables using discovery. |
| `400 BRIDGE_AI_LEADSCOUT_0016` for an unknown template `mediaId` on Agents outbound | The conversation may already have been created or recovered before this error. Inspect it before retrying. |

[Release conversation](https://docs.bridge.new/api-reference/conversations-api/release-conversation.md) is a separate operation with business effects. A `204` has no response body. Release only when ending that conversation is your intended action.

## Request a LeadScout handoff to a human

For a LeadScout conversation, resolve the human's [Bridge User ID or email](https://docs.bridge.new/guides/identifiers.md), then call the [manual handoff endpoint](https://docs.bridge.new/api-reference/leadscout-api/request-a-manual-handoff-of-a-leadscout-conversation-to-internal-users.md). This operation is specific to LeadScout; do not assume it applies to a Service Agent.

```bash theme={null}
curl --fail-with-body --request POST \
  "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/$WORKSPACE_ID/leadscout/conversations/$CONVERSATION_ID/handoff" \
  --header "x-api-key: $BRIDGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "assignees": [
      {"identifier": "f0000002-0000-4000-8000-000000000002", "identifierType": "ID"}
    ]
  }'
```

A `202` acknowledges the request. Save its `trackingId` and `conversationId`; acceptance does not prove that assignment has completed or that a human has read or answered the conversation. The reference does not publish a handoff tracking endpoint, so do not construct one from `trackingId`.

Continue with [error handling](https://docs.bridge.new/error-codes.md) and [webhook receiving](https://docs.bridge.new/webhooks/receive-events.md) to connect this workflow to your system.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.