Channels management

Retrieving channels

Retrieve list of channels

Get workspace channels

get

Get the channels configured for a workspace

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

limitinteger · min: 1 · max: 1000Optional

Limits the number of results to return

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

platformany ofOptional

Filter based on platform name

string · min: 3 · max: 60OptionalPattern: ^[A-Za-z0-9-]+$

or

string[]Optional

conferencialbooleanOptional

Filter based on conferencial flag

Default: false

onlyMyChannelsbooleanOptional

Filter only channels I have access to

Default: false

statusany ofOptional

Filter based on channel status

string · enumOptionalDefault: previewPossible values:

or

stringOptional

useCaseTypestring · enumOptionalPossible values:

channelIdsstring · uuid[]Optional

Filter based on channel IDs

resourceOwnerIdstring · uuid[]Optional

Filter based on resource owner IDs

resourceOwnerIdentifierstring[]Optional

Filter based on resource owner identifiers

Responses

200

OK

application/json

404

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/channels

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "platformId": "text",
      "name": "text",
      "connectorId": "123e4567-e89b-12d3-a456-426614174000",
      "identifier": "text",
      "status": "active",
      "contactIdentifierKeyOverride": "text",
      "contactIdentifierFormatOverride": {
        "type": "none",
        "pattern": "text"
      },
      "platformServiceUrlOverride": "text",
      "platformServiceVersionOverride": "1.0",
      "platformServiceProtocolOverride": "http",
      "platformMessageJsonSchemaOverride": {},
      "platformTemplateEngineOverride": "default",
      "capabilities": {
        "messaging": {
          "messaging": {
            "displayName": "text",
            "status": "text",
            "name": "text",
            "version": 1,
            "updatedAt": "2026-02-05T00:11:51.239Z",
            "createdAt": "2026-02-05T00:11:51.239Z",
            "expiresAt": "2026-02-05T00:11:51.239Z",
            "outgoing": {
              "displayName": "text",
              "status": "text",
              "name": "text",
              "version": 1,
              "updatedAt": "2026-02-05T00:11:51.239Z",
              "createdAt": "2026-02-05T00:11:51.239Z",
              "expiresAt": "2026-02-05T00:11:51.239Z",
              "mms": {
                "displayName": "text",
                "status": "text",
                "name": "text",
                "version": 1,
                "paused": true,
                "updatedAt": "2026-02-05T00:11:51.239Z",
                "createdAt": "2026-02-05T00:11:51.239Z",
                "expiresAt": "2026-02-05T00:11:51.239Z"
              },
              "media": {
                "textFallback": {
                  "displayName": "text",
                  "status": "text",
                  "name": "text",
                  "version": 1,
                  "paused": true,
                  "updatedAt": "2026-02-05T00:11:51.239Z",
                  "createdAt": "2026-02-05T00:11:51.239Z",
                  "expiresAt": "2026-02-05T00:11:51.239Z"
                }
              },
              "mmLite": {
                "displayName": "text",
                "status": "text",
                "name": "text",
                "version": 1,
                "paused": true,
                "updatedAt": "2026-02-05T00:11:51.239Z",
                "createdAt": "2026-02-05T00:11:51.239Z",
                "expiresAt": "2026-02-05T00:11:51.239Z"
              }
            },
            "incoming": {
              "displayName": "text",
              "status": "text",
              "name": "text",
              "version": 1,
              "updatedAt": "2026-02-05T00:11:51.239Z",
              "createdAt": "2026-02-05T00:11:51.239Z",
              "expiresAt": "2026-02-05T00:11:51.239Z",
              "mms": {
                "displayName": "text",
                "status": "text",
                "name": "text",
                "version": 1,
                "paused": true,
                "updatedAt": "2026-02-05T00:11:51.239Z",
                "createdAt": "2026-02-05T00:11:51.239Z",
                "expiresAt": "2026-02-05T00:11:51.239Z"
              }
            }
          },
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "voice": {
          "voice": {
            "displayName": "text",
            "status": "text",
            "name": "text",
            "version": 1,
            "updatedAt": "2026-02-05T00:11:51.239Z",
            "createdAt": "2026-02-05T00:11:51.239Z",
            "expiresAt": "2026-02-05T00:11:51.239Z",
            "recording": {
              "displayName": "text",
              "status": "text",
              "name": "text",
              "version": 1,
              "paused": true,
              "updatedAt": "2026-02-05T00:11:51.239Z",
              "createdAt": "2026-02-05T00:11:51.239Z",
              "expiresAt": "2026-02-05T00:11:51.239Z"
            }
          },
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "settings": [
        {
          "key": "text",
          "value": "text",
          "displayName": "text",
          "description": "text",
          "visibility": "public"
        }
      ],
      "connectionParams": [
        {
          "key": "text",
          "value": "text",
          "displayName": "text",
          "description": "text",
          "visibility": "public"
        }
      ],
      "preferences": {
        "disableProfileFetching": true,
        "explicitMarketingOptOut": true,
        "trackAdInitiatedThreads": null,
        "ignoreSuppressionChecks": true,
        "isPrivate": true,
        "disallowMmLite": true
      },
      "useCaseId": "text",
      "useCaseType": "transactional",
      "channelMessageType": "promotional",
      "suites": [
        "marketing"
      ],
      "resourceOwners": {
        "ANY_ADDITIONAL_PROPERTY": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "user"
        }
      },
      "createdAt": "2026-02-05T00:11:51.239Z",
      "updatedAt": "2026-02-05T00:11:51.239Z"
    }
  ],
  "nextPageToken": "text"
}

Retrieve a specific channel

Get channel

get

Retrieve a specific workspace channel

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Responses

200

OK

application/json

404

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/channels/{channelId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "platformId": "text",
  "name": "text",
  "connectorId": "123e4567-e89b-12d3-a456-426614174000",
  "identifier": "text",
  "status": "active",
  "contactIdentifierKeyOverride": "text",
  "contactIdentifierFormatOverride": {
    "type": "none",
    "pattern": "text"
  },
  "platformServiceUrlOverride": "text",
  "platformServiceVersionOverride": "1.0",
  "platformServiceProtocolOverride": "http",
  "platformMessageJsonSchemaOverride": {},
  "platformTemplateEngineOverride": "default",
  "capabilities": {
    "messaging": {
      "messaging": {
        "displayName": "text",
        "status": "text",
        "name": "text",
        "version": 1,
        "updatedAt": "2026-02-05T00:11:51.239Z",
        "createdAt": "2026-02-05T00:11:51.239Z",
        "expiresAt": "2026-02-05T00:11:51.239Z",
        "outgoing": {
          "displayName": "text",
          "status": "text",
          "name": "text",
          "version": 1,
          "updatedAt": "2026-02-05T00:11:51.239Z",
          "createdAt": "2026-02-05T00:11:51.239Z",
          "expiresAt": "2026-02-05T00:11:51.239Z",
          "mms": {
            "displayName": "text",
            "status": "text",
            "name": "text",
            "version": 1,
            "paused": true,
            "updatedAt": "2026-02-05T00:11:51.239Z",
            "createdAt": "2026-02-05T00:11:51.239Z",
            "expiresAt": "2026-02-05T00:11:51.239Z"
          },
          "media": {
            "textFallback": {
              "displayName": "text",
              "status": "text",
              "name": "text",
              "version": 1,
              "paused": true,
              "updatedAt": "2026-02-05T00:11:51.239Z",
              "createdAt": "2026-02-05T00:11:51.239Z",
              "expiresAt": "2026-02-05T00:11:51.239Z"
            }
          },
          "mmLite": {
            "displayName": "text",
            "status": "text",
            "name": "text",
            "version": 1,
            "paused": true,
            "updatedAt": "2026-02-05T00:11:51.239Z",
            "createdAt": "2026-02-05T00:11:51.239Z",
            "expiresAt": "2026-02-05T00:11:51.239Z"
          }
        },
        "incoming": {
          "displayName": "text",
          "status": "text",
          "name": "text",
          "version": 1,
          "updatedAt": "2026-02-05T00:11:51.239Z",
          "createdAt": "2026-02-05T00:11:51.239Z",
          "expiresAt": "2026-02-05T00:11:51.239Z",
          "mms": {
            "displayName": "text",
            "status": "text",
            "name": "text",
            "version": 1,
            "paused": true,
            "updatedAt": "2026-02-05T00:11:51.239Z",
            "createdAt": "2026-02-05T00:11:51.239Z",
            "expiresAt": "2026-02-05T00:11:51.239Z"
          }
        }
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "voice": {
      "voice": {
        "displayName": "text",
        "status": "text",
        "name": "text",
        "version": 1,
        "updatedAt": "2026-02-05T00:11:51.239Z",
        "createdAt": "2026-02-05T00:11:51.239Z",
        "expiresAt": "2026-02-05T00:11:51.239Z",
        "recording": {
          "displayName": "text",
          "status": "text",
          "name": "text",
          "version": 1,
          "paused": true,
          "updatedAt": "2026-02-05T00:11:51.239Z",
          "createdAt": "2026-02-05T00:11:51.239Z",
          "expiresAt": "2026-02-05T00:11:51.239Z"
        }
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "settings": [
    {
      "key": "text",
      "value": "text",
      "displayName": "text",
      "description": "text",
      "visibility": "public"
    }
  ],
  "connectionParams": [
    {
      "key": "text",
      "value": "text",
      "displayName": "text",
      "description": "text",
      "visibility": "public"
    }
  ],
  "preferences": {
    "disableProfileFetching": true,
    "explicitMarketingOptOut": true,
    "trackAdInitiatedThreads": null,
    "ignoreSuppressionChecks": true,
    "isPrivate": true,
    "disallowMmLite": true
  },
  "useCaseId": "text",
  "useCaseType": "transactional",
  "channelMessageType": "promotional",
  "suites": [
    "marketing"
  ],
  "resourceOwners": {
    "ANY_ADDITIONAL_PROPERTY": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "user"
    }
  },
  "createdAt": "2026-02-05T00:11:51.239Z",
  "updatedAt": "2026-02-05T00:11:51.239Z"
}

Check if customer service window is open

For some channels it is only possible to send non template messages if the customer service window is open. The following endpoint will return the expiry time for any active service windows

Get channel details for a contact

get

Retrieve channel information for a given contact.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

contactIdstring · uuidRequired

The ID for a contact

Query parameters

contactIdentifierValuestringOptional

The receiver identifier value.

Responses

200

OK

application/json

404

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "serviceWindowExpireAt": "2026-02-05T00:11:51.239Z",
  "isPermanentSession": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}