Update a call

Update an active call resource. You can use this request to do additional actions:

• You can use this request to hangup the call by setting status to completed

• It can also be used to update the callFlow of the call. Commands of the new callFlow will be executed after the Patch.

CallFlowCommand

Check bellow the available commands when initiating an outbound call. In order to assess the options of each command, you may explore each command section.

type: string
enum:
  - answer
  - hangup
  - playback
  - say
  - gather
  - record
  - bridge
  - pause
  - ringing

Update call

patch

Update a call

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

callIdstring · uuidRequired

The ID for a call

channelIdstring · uuidRequired

The ID for a channel

Body

application/json

statusstring · enum · nullableOptionalPossible values:

Responses

202

Call update accepted

application/json

idstring · uuidRequired

channelIdstring · uuidRequired

fromstringRequired

tostringRequired

parentIdstring · uuidOptional

directionstring · enumRequiredPossible values:

statusstring · enumRequiredPossible values:

reasonstringOptional

typestring · enumRequiredPossible values:

durationintegerOptional

hangupCauseCodeintegerOptional

hangupSourcestring · enum · nullableOptionalPossible values:

hangupSipCodestringOptional

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

ringingAtstring · date-timeOptional

answeredAtstring · date-timeOptional

endedAtstring · date-timeOptional

scheduledForstring · date-timeOptional

sipTypestring · enumOptionalPossible values:

tagsstring[] · max: 10Optional

Tags to associate with the call. Tags are converted to lower case and tags that do not exist are automatically created. You can view your created tags in the UI. You can specify up to 10 tags per call.

400

The request did not pass validation

application/json

404

The request did not pass validation

application/json

422

The request did not pass validation

application/json

patch

/workspaces/{workspaceId}/channels/{channelId}/calls/{callId}

HTTPcURLJavaScriptPython

PATCH /workspaces/{workspaceId}/channels/{channelId}/calls/{callId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 135

{
  "status": "completed",
  "callFlow": [
    {
      "command": "answer",
      "options": {},
      "conditions": [
        {
          "variable": "keys",
          "operator": "eq",
          "value": "text"
        }
      ]
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "from": "text",
  "to": "text",
  "originator": {
    "contact": {
      "id": "text",
      "identifierKey": "text",
      "identifierValue": "text"
    },
    "number": {
      "type": "pstn",
      "number": "text",
      "anonymous": true,
      "callerIdName": "text",
      "identity": "text",
      "countryIsoCode": "text",
      "pstnNumberType": "text"
    }
  },
  "receiver": {
    "contact": {
      "id": "text",
      "identifierKey": "text",
      "identifierValue": "text"
    },
    "number": {
      "type": "pstn",
      "number": "text",
      "anonymous": true,
      "callerIdName": "text",
      "identity": "text",
      "countryIsoCode": "text",
      "pstnNumberType": "text"
    }
  },
  "parentId": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "incoming",
  "status": "accepted",
  "reason": "text",
  "type": "pstn",
  "duration": 1,
  "hangupCauseCode": 1,
  "hangupSource": "callee",
  "hangupSipCode": "text",
  "createdAt": "2026-03-18T00:03:21.873Z",
  "updatedAt": "2026-03-18T00:03:21.873Z",
  "ringingAt": "2026-03-18T00:03:21.873Z",
  "answeredAt": "2026-03-18T00:03:21.873Z",
  "endedAt": "2026-03-18T00:03:21.873Z",
  "scheduledFor": "2026-03-18T00:03:21.873Z",
  "callFlow": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "commands": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "callId": "123e4567-e89b-12d3-a456-426614174000",
        "callFlowId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "text",
        "command": "text",
        "conditions": [
          {
            "variable": "keys",
            "operator": "eq",
            "value": "text"
          }
        ]
      }
    ]
  },
  "notification": {
    "url": "text"
  },
  "qualityInsights": {
    "mos": "text",
    "pdd": "text"
  },
  "sipInsights": {
    "hangupSipCode": "text",
    "edgeRegion": "text",
    "providerName": "text",
    "userAgent": "text",
    "remoteSignallingIp": "text",
    "remoteMediaIp": "text"
  },
  "amdResult": {
    "result": "human",
    "speech": "text",
    "locale": "text"
  },
  "sipType": "elastic",
  "tags": [
    "text"
  ]
}

Example 1: Update a call by answering

Request Headers

curl -X PATCH "https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/calls/{channelId}" \
     -H "Authorization: AccessKey YOUR_SECRET_TOKEN"

Request Body

Response

Example 2: Update a call by sending ringing, pause for 2 seconds, answer and play an announcement

Request Headers

curl -X PATCH "https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/calls/{channelId}" \
     -H "Authorization: AccessKey YOUR_SECRET_TOKEN"

Request Body

Response