Skip to main content
GET
/
v1
/
workspaces
/
{workspaceId}
/
conversations
List conversations with flexible filtering
curl --request GET \
  --url https://api.bridge.new/v1/workspaces/{workspaceId}/conversations \
  --header 'X-API-Key: <api-key>'
{
  "conversations": [
    {
      "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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

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"

Query Parameters

externalUser
object

External user identifier to filter conversations

internalUser
object

Internal user identifier to filter conversations

status
enum<string>

Conversation status filter

Available options:
active,
archived,
ghost
Example:

"active"

page
integer
default:1

Page number for pagination

Required range: x >= 1
Example:

1

limit
integer
default:20

Number of conversations per page

Required range: 20 <= x <= 100
Example:

20

Response

Conversations retrieved successfully

conversations
object[]
required

Array of conversations

pagination
object
required
I