openai@v4

Communicate with OpenAI's API, no API key needed.


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

Parameters

Name	Type	Required	Default	Description
`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`	Turns the sound on. accepts `${{ }}`
`feedback.sound`	`beep`, `loading`, `heartbeat`		`"heartbeat"`	Built-in sound to play, unless `audioFile` is set. 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 `${{ }}`
`secret`	string			Optional: your own OpenAI API key, to have OpenAI bill the tokens on your account (any endpoint and any of its models then work). Without it, nothing to set up: Callr bills the tokens, the endpoint must be `chat/completions` or `responses`, and `properties.model` must be one of the OpenAI models listed in the AI section of your rates (Billing > Pricing). 1..255 characters
`endpoint`	string	yes		OpenAI API endpoint, after https://api.openai.com/v1/, for example chat/completions. 1..255 characters
`timeout`	integer		`20`	Seconds to wait for the response. 1..60 · accepts `${{ }}`
`properties`	object	yes		Body of the request, as documented by OpenAI for the endpoint (model, messages...).

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

How it works

Same as openai@v3, except that secret is optional.

Nothing to set up: without secret, no API key is needed and Callr bills the tokens per model (see the AI section of your rates, Billing > Pricing). The endpoint must then be chat/completions or responses, and properties.model one of the OpenAI models listed in the AI section of your rates (Billing > Pricing). Without properties.model, the default model of your account answers when it is an OpenAI one, else gpt-6.1-terra. When the model asked is no longer available (deprecated by OpenAI), the closest model answers instead.

Your own OpenAI API key (optional): with secret, OpenAI bills the tokens on your account, and any endpoint and any model you have access to work.

The recent reasoning models (gpt-5.5, gpt-5.6-*, gpt-6*) refuse any temperature but 1 on chat/completions, unless the properties have reasoning_effort: none: leave temperature out to let the model choose.

Examples

No API key needed

No key and no model: the default model of your account answers, the tokens are billed by Callr.

- label: ask
  action: recognize@v3
  params:
    tts:
      text: Ask me anything
  result: $question

- action: openai@v4
  params:
    endpoint: chat/completions
    properties:
      messages:
        - role: system
          content: You answer on the phone, in one short sentence.
        - role: user
          content: ${{ $question.text }}
    timeout: 5
    # feedback: sound played to the caller while waiting for OpenAI,
    # disabled by default
    feedback:
      enabled: true
      delay: 0 # (0..60) seconds
      sound: heartbeat # beep|heartbeat|loading
  result: $openai

With your OpenAI key

With secret, OpenAI bills your account: keep the key in the secrets of the account (Secrets button of the Actions page) rather than in the scenario.

- action: openai@v4
  params:
    secret: ${{ secrets.OPENAI_KEY }}
    endpoint: chat/completions
    properties:
      model: gpt-6.1-terra
      messages: ${{ $messages }}
    timeout: 5
  result: $openai

Result handling

- if: >
    !$openai.ok || !$openai?.choices?.length
  then:
    - action: play@v3
      params:
        tts:
          text: I am sorry, I was not able to reply within the time limit.
    - goto:
        label: ask

- action: play@v3
  params:
    tts:
      text: ${{ $openai.choices[0].message.content }}

Result

Set result: $myVariable to keep it. Response of the OpenAI API. On success, the fields of the OpenAI response (for chat/completions: id, choices, usage...) and ok: true

Field	Type	Description
`ok`	boolean	`true` when OpenAI answered with HTTP 200
`error`	string	Only when `ok` is `false`: `timeout`, `code != 200`, `no secret`, `no properties`, `no endpoint`, or the network error

{
  "ok": true,
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "model": "gpt-6.1-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Older versions

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

openai@v3: Communicate with OpenAI's API
openai@v2: Communicate with OpenAI's API
openai@v1: Use openai@v2 instead openai@v1 is deprecated, use openai@v4