openai@v3

Communicate with OpenAI's API.


Version	`openai@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
`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 `${{ }}`
`secret`	string	yes		1..255 characters
`endpoint`	string	yes		1..255 characters
`timeout`	integer		`20`	1..60 · accepts `${{ }}`
`properties`	object	yes

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

Examples

To communicate with OpenAI's API, you need to create an API key https://platform.openai.com/docs/api-reference/authentication

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

- action: openai@v3
  params:
    secret: MySecretApiKeyFromOpenAI
    endpoint: chat/completions
    properties:
      model: gpt-5.4
      messages: ${{ $messages }}
    timeout: 5
    # feedback: sound played to the caller while waiting for OpenAI
    # (same as audio in openai@v2), disabled by default
    feedback:
      enabled: true
      delay: 0 # (0..60) seconds
      sound: heartbeat # beep|heartbeat|loading
      # or an audio file of your library instead of sound:
      # audioFile:
      #   sid: 'fdsanjkf'
  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-4o-mini",
  "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@v2: Communicate with OpenAI's API
openai@v1: Use openai@v2 instead openai@v1 is deprecated, use openai@v3