Skip to main content
POST
/
v1
/
workspaces
/
{workspaceId}
/
conversations
curl --request POST \
  --url https://api.bridge.new/v1/workspaces/{workspaceId}/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "externalParticipants": [
    {
      "identifier": "john.doe@example.com",
      "type": "email"
    },
    {
      "identifier": "+1-555-123-4567",
      "type": "phone"
    }
  ],
  "status": "ghost"
}'
{
  "id": "conv_abc123",
  "workspaceId": "ws_abc123",
  "externalParticipants": [
    {
      "identifier": "john.doe@example.com",
      "type": "email",
      "role": "external",
      "joinedAt": "2024-01-15T10:30:00Z",
      "lastSeenAt": "2024-01-15T15:45:00Z"
    }
  ],
  "internalParticipants": [
    {
      "identifier": "john.doe@example.com",
      "type": "email",
      "role": "external",
      "joinedAt": "2024-01-15T10:30:00Z",
      "lastSeenAt": "2024-01-15T15:45:00Z"
    }
  ],
  "name": "Support Request - John Doe",
  "status": "active",
  "teamId": "team_sales",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T15:45:00Z"
}

Authorizations

​
X-API-Key
string
header
required

API Key authentication for machine-to-machine communication.

Authentication Process:

  1. Generate an access key and secret key pair from your Bridge dashboard
  2. Include the access key in the X-API-Key header
  3. Sign your requests using the secret key (HMAC-SHA256)
  4. Include the signature in the X-API-Signature header

Request Signing:

  • Create a string to sign: {HTTP_METHOD}\n{REQUEST_PATH}\n{REQUEST_BODY}\n{TIMESTAMP}
  • Generate HMAC-SHA256 signature using your secret key
  • Include timestamp in X-API-Timestamp header (Unix timestamp)
  • Include signature in X-API-Signature header

Example Headers:

X-API-Key: ak_1234567890abcdef
X-API-Timestamp: 1642234567
X-API-Signature: a1b2c3d4e5f6...

Path Parameters

​
workspaceId
string
required

Unique identifier of the workspace

Example:

"ws_abc123"

Body

application/json
  • Option 1
  • Option 2
  • Option 3
​
externalParticipants
object[]
required

Array of external user identifiers (required)

Minimum length: 1
​
internalParticipants
object[]

Array of internal user identifiers (optional, mutually exclusive with teamId)

​
teamId
string

Team UUID for round-robin assignment (optional, mutually exclusive with internalParticipants)

Example:

"SOME-TEAM-UUID"

​
name
string

Optional name/title for the conversation

Example:

"Support Request - John Doe"

​
status
enum<string>
default:active

Initial conversation status - 'active' for visible conversations, 'ghost' for invisible until first interaction

Available options:
active,
ghost

Response

Conversation created successfully

​
id
string
required

Unique identifier for the conversation

Example:

"conv_abc123"

​
workspaceId
string
required

Unique identifier of the workspace this conversation belongs to

Example:

"ws_abc123"

​
externalParticipants
object[]
required

Array of external participants

​
status
enum<string>
required

Current conversation status - 'active' for visible conversations, 'ghost' for invisible until first interaction, 'archived' for completed conversations

Available options:
active,
archived,
ghost
Example:

"active"

​
createdAt
string<date-time>
required

Timestamp when the conversation was created

Example:

"2024-01-15T10:30:00Z"

​
updatedAt
string<date-time>
required

Timestamp when the conversation was last updated

Example:

"2024-01-15T15:45:00Z"

​
internalParticipants
object[]

Array of internal participants

​
name
string

Optional name/title for the conversation

Example:

"Support Request - John Doe"

​
teamId
string

Team ID if assigned via round-robin

Example:

"team_sales"

⌘I