Update a call

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

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

Update call status

Check bellow the available call status.

 status:
    type: string
    nullable: true
    enum:
      - completed

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

Update a call

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

Authorization

Path parameters

workspaceId*string (uuid)

The ID of the workspace

callId*string (uuid)

The ID for a call

channelId*string (uuid)

The ID for a channel

Body

statusnullable enum

completed

callFlowarray of CallFlowCommand

Response

Call update accepted

Body

id*Id-2 (string (uuid))

channelId*ChannelId (string (uuid))

from*string

to*string

originator*ChannelCallOriginatorOrReceiver

receiver*ChannelCallOriginatorOrReceiver

parentIdId-2 (string (uuid))

direction*Direction (enum)

incomingoutgoing

status*Status-4 (enum)

acceptedstartingringingongoingcompletedno-answerbusyfailedcancelled

reasonstring

type*Type-2 (enum)

pstnsipwebrtc

durationinteger

hangupCauseCodeinteger

hangupSourcenullable HangupSource (enum)

calleecallerapitimeoutmedia-timeoutnone

hangupSipCodestring

createdAt*string (date-time)

updatedAt*string (date-time)

ringingAtstring (date-time)

answeredAtstring (date-time)

endedAtstring (date-time)

callFlowCallFlow

notificationCallNotification

qualityInsightsqualityInsights

sipInsightssignallingInsights

Request

const response = await fetch('/workspaces/{workspaceId}/channels/{channelId}/calls/{callId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "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": false,
      "callerIdName": "text",
      "identity": "text",
      "countryIsoCode": "text",
      "pstnNumberType": "text"
    }
  },
  "receiver": {
    "contact": {
      "id": "text",
      "identifierKey": "text",
      "identifierValue": "text"
    },
    "number": {
      "type": "pstn",
      "number": "text",
      "anonymous": false,
      "callerIdName": "text",
      "identity": "text",
      "countryIsoCode": "text",
      "pstnNumberType": "text"
    }
  },
  "parentId": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "incoming",
  "status": "accepted",
  "reason": "text",
  "type": "pstn",
  "hangupSource": "callee",
  "hangupSipCode": "text",
  "createdAt": "2024-04-29T14:31:23.620Z",
  "updatedAt": "2024-04-29T14:31:23.620Z",
  "ringingAt": "2024-04-29T14:31:23.620Z",
  "answeredAt": "2024-04-29T14:31:23.620Z",
  "endedAt": "2024-04-29T14:31:23.620Z",
  "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"
      }
    ]
  },
  "notification": {
    "url": "text"
  },
  "qualityInsights": {
    "mos": "text",
    "pdd": "text"
  },
  "sipInsights": {
    "hangupSipCode": "text",
    "edgeRegion": "text",
    "providerName": "text",
    "userAgent": "text",
    "remoteSignallingIp": "text",
    "remoteMediaIp": "text"
  }
}

Example 1: Update a call by answering

curl -X "PATCH" "https://nest.messagebird.one/workspaces/8bc02f53-87ac-48d2-b4fd-c2cf856a305f/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6
/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
     -H 'Authorization: Bearer {Token}'

{
  "status": "completed",
  "callFlow": [
    {
      "command": "answer",
      "options": {
        "media": [
          "string"
        ],
        "loop": 0,
        "timeout": 0
      }
    }
  ]
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "from": "string",
  "to": "string",
  "originator": {
    "contact": {
      "id": "string",
      "identifierKey": "string",
      "identifierValue": "string"
    },
    "number": {
      "type": "pstn",
      "number": "string",
      "anonymous": true,
      "callerIdName": "string",
      "identity": "string",
      "countryIsoCode": "string",
      "pstnNumberType": "string"
    }
  },
  "direction": "incoming",
  "status": "accepted",
  "reason": "string",
  "type": "pstn",
  "duration": 0,
  "hangupCauseCode": 0,
  "hangupSource": "callee",
  "hangupSipCode": "string",
  "createdAt": "2023-10-25T14:36:18.575Z",
  "updatedAt": "2023-10-25T14:36:18.575Z",
  "ringingAt": "2023-10-25T14:36:18.575Z",
  "answeredAt": "2023-10-25T14:36:18.575Z",
  "endedAt": "2023-10-25T14:36:18.575Z",
  "callFlow": {
    "commands": [
      {
        "callFlowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "string",
        "command": "string"
      }
    ]
  },
  "qualityInsights": {
    "mos": "string",
    "pdd": "string"
  },
  "sipInsights": {
    "hangupSipCode": "string",
    "edgeRegion": "string",
    "providerName": "string",
    "userAgent": "string",
    "remoteSignallingIp": "string",
    "remoteMediaIp": "string"
  }
}

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

curl -X "PATCH" "https://nest.messagebird.one/workspaces/8bc02f53-87ac-48d2-b4fd-c2cf856a305f/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6
/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
     -H 'Authorization: Bearer {Token}'

{
  "callFlow": [
    {
      "command": "ringing"
    },
    {
      "command": "pause",
      "options": {
        "pauseSeconds": 2
      }
    },
    {
      "command": "answer"
    },
    {
      "command": "say",
      "options": {
        "text": "Sorry, we don't have available agents now. Please call later. GoodBye.",
        "locale": "en-GB",
        "voice": "male"
      }
    },
    {
      "command": "hangup"
    }
  ]
}

{
  "id": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
  "channelId": "db53c357-92e3-4f3d-babe-159573940a50",
  "originator": {
    "contact": {
      "id": "1ea5d8c8-3f5e-4cc0-bb92-47b099d317c0",
      "identifierKey": "phonenumber",
      "identifierValue": "+351910648518"
    },
    "number": {
      "type": "pstn",
      "number": "+351910648518",
      "callerIdName": "Jose G",
      "countryIsoCode": "PT"
    }
  },
  "receiver": {
    "number": {
      "type": "pstn",
      "number": "+3197058016589",
      "countryIsoCode": "NL"
    }
  },
  "from": "+351910648518",
  "to": "+3197058016589",
  "direction": "incoming",
  "status": "starting",
  "type": "pstn",
  "duration": 0,
  "callFlow": {
    "id": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84",
    "commands": [
      {
        "id": "2c27c266-856d-4ae2-abfe-19a3388bdfaf",
        "callId": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
        "command": "ringing",
        "status": "accepted",
        "callFlowId": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84"
      },
      {
        "id": "f39efa8f-5c8e-40f1-99a2-9b3eab040734",
        "callId": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
        "command": "pause",
        "status": "accepted",
        "callFlowId": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84"
      },
      {
        "id": "1d093dc0-3646-49d5-9125-939da797961a",
        "callId": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
        "command": "answer",
        "status": "accepted",
        "callFlowId": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84"
      },
      {
        "id": "57f960c6-455f-4884-b4de-fc017c0f1be3",
        "callId": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
        "command": "say",
        "status": "accepted",
        "callFlowId": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84"
      },
      {
        "id": "cf8a8557-f3ba-41a5-a21f-2543f7268380",
        "callId": "a78dd93c-08fb-450b-8651-0def9cf77cf9",
        "command": "hangup",
        "status": "accepted",
        "callFlowId": "c4b84cee-66bb-4f1f-b43c-4b63be02ef84"
      }
    ]
  },
  "createdAt": "2024-03-01T16:46:50.158Z",
  "updatedAt": "2024-03-01T16:46:50.45Z"
}

Last updated 1 month ago