fetch@v3

Fetch HTTP resource.


Version	`fetch@v3`
Runs in	`inbound-call` and your own branches · `api-initiated` and `inbound-sms` · `hangup`, `postHangup` and `events.ready`

Parameters

Name	Type	Required	Default	Description
`url`	string	yes		1..1024 characters · accepts `${{ }}`
`method`	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`		`"GET"`	accepts `${{ }}`
`headers`	object			accepts `${{ }}`
`body`	string			1..10240 characters
`responseFormat`	`auto`, `json`		`"auto"`	accepts `${{ }}`
`timeout`	integer		`10`	1..60 · accepts `${{ }}`
`feedback`	object			Sound played to the caller while the action runs: a built-in sound or an audio file of your library (at most one of sound / audioFile).
`feedback.enabled`	boolean		`false`	accepts `${{ }}`
`feedback.sound`	`beep`, `loading`, `heartbeat`		`"heartbeat"`	accepts `${{ }}`
`feedback.audioFile`	object			An audio file of your library, by its SID (REST API v2 identifier). audio file of your library: `sid`
`feedback.delay`	number		`0`	Seconds to wait before playing: 0..60 accepts `${{ }}`

Every parameter that accepts ${{ }} can be computed from an expression.

How it works

fetch@v3 is built with the Fetch API in mind. Same as fetch@v2, except that audio is now feedback: the sound played to the caller while the request runs (disabled by default). Set at most one of sound / audioFile.

NOTE: if you do not specify a result variable, the fetch is run asynchronously and the action returns immediately, not blocking the voice flow.

Examples

Short example

- action: fetch@v3
  params:
    url: https://api.example.com/json/
  result: $response

Full example

- action: fetch@v3
  params:
    feedback:
      enabled: true # default is false
      delay: 0 # (0..60) seconds, default is 0
      sound: heartbeat # beep|heartbeat|loading
      # or an audio file of your library instead of sound:
      # audioFile:
      #   sid: 'fdsanjkf'
    url: "https://api.example.com/json/firstname?number=\
      ${{ encodeURIComponent(call.fromNumber) }}"
    method: POST # default is GET
    headers:
      # examples headers you can add
      Authorization: Bearer ${{ $token }}
      Content-Type: application/json
      Custom-Header: ${{ $customHeader }}
      # added automatically: Callr-RunID and Callr-RunType,
      # plus Callr-CallID and Callr-CallLeg on inbound calls
    body: ${{ JSON.stringify(call) }}
    responseFormat: json
    timeout: 10 # (int) 1..60, default is 10
  result: $response

async example for an inbound call

- action: fetch@v3
  params:
    url: https://api.example.com/cdr
    method: POST
    body: |
      {
        "from": "Callr",
        "call": ${{ JSON.stringify(call) }}
      }
  # no 'result' parameter -> async fetch

Using the result

- if: '!$response.ok'
  then:
    - action: log@v1
      params:
        message: >
          Error fetching resource: ${{ $response.statusText }}
    - action: hangup@v1

- action: play@v3
  params:
    tts:
      text: Hello ${{ $response.json.firstname }}!

Result

Set result: $myVariable to keep it. HTTP response of fetch

Field	Type	Description
`ok`	boolean	`true` when the HTTP status is 2xx
`status`	integer	HTTP status code, `0` when the request failed (timeout, DNS error, connection refused...)
`statusText`	string	First status line of the response (for example `HTTP/1.1 200 OK`), or the error message when the request failed
`headers`	object	Response headers, by name as sent by the server. Empty when the request failed
`body`	string or null	Response body, `null` when the request failed
`json`	any	Body parsed as JSON. Only present when the response is `application/json` or with `responseFormat: json` (`null` when the body is not valid JSON)

{
  "ok": true,
  "status": 200,
  "statusText": "HTTP/1.1 200 OK",
  "headers": {
    "content-type": "application/json",
    "content-length": "21"
  },
  "body": "{\"firstname\":\"Alice\"}",
  "json": {
    "firstname": "Alice"
  }
}

Older versions

Older versions keep working in existing scenarios. Use the version above in new scenarios.

fetch@v2: Fetch HTTP resource
fetch@v1: Use fetch@v2 instead fetch@v1 is deprecated, use fetch@v3