curl --request POST \
--url https://general-runtime.voiceflow.com/v4/interact \
--header 'Content-Type: application/json' \
--header 'authorization: <api-key>' \
--data '
{
"action": {
"type": "launch",
"payload": {
"persona": "<string>"
},
"diagramID": "<string>",
"time": 123,
"metadata": {}
},
"variables": {},
"state": "<unknown>",
"config": {}
}
'import requests
url = "https://general-runtime.voiceflow.com/v4/interact"
payload = {
"action": {
"type": "launch",
"payload": { "persona": "<string>" },
"diagramID": "<string>",
"time": 123,
"metadata": {}
},
"variables": {},
"state": "<unknown>",
"config": {}
}
headers = {
"authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: {
type: 'launch',
payload: {persona: '<string>'},
diagramID: '<string>',
time: 123,
metadata: {}
},
variables: {},
state: '<unknown>',
config: {}
})
};
fetch('https://general-runtime.voiceflow.com/v4/interact', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://general-runtime.voiceflow.com/v4/interact",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => [
'type' => 'launch',
'payload' => [
'persona' => '<string>'
],
'diagramID' => '<string>',
'time' => 123,
'metadata' => [
]
],
'variables' => [
],
'state' => '<unknown>',
'config' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://general-runtime.voiceflow.com/v4/interact"
payload := strings.NewReader("{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://general-runtime.voiceflow.com/v4/interact")
.header("authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://general-runtime.voiceflow.com/v4/interact")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}"
response = http.request(request)
puts response.read_body{
"traces": [
{
"type": "audio",
"payload": {
"state": "start",
"messageID": "<string>",
"delay": 123
},
"paths": [
{
"label": "<string>",
"event": {
"type": "<string>",
"payload": "<unknown>",
"diagramID": "<string>",
"time": 123,
"metadata": {}
}
}
],
"defaultPath": 123,
"time": 123,
"turnID": "<string>",
"handleID": "<string>"
}
]
}{
"traces": [
{
"type": "audio",
"payload": {
"state": "start",
"messageID": "<string>",
"delay": 123
},
"paths": [
{
"label": "<string>",
"event": {
"type": "<string>",
"payload": "<unknown>",
"diagramID": "<string>",
"time": 123,
"metadata": {}
}
}
],
"defaultPath": 123,
"time": 123,
"turnID": "<string>",
"handleID": "<string>"
}
]
}Interact (non-stream)
Send an action and receive an array of traces in response.
curl --request POST \
--url https://general-runtime.voiceflow.com/v4/interact \
--header 'Content-Type: application/json' \
--header 'authorization: <api-key>' \
--data '
{
"action": {
"type": "launch",
"payload": {
"persona": "<string>"
},
"diagramID": "<string>",
"time": 123,
"metadata": {}
},
"variables": {},
"state": "<unknown>",
"config": {}
}
'import requests
url = "https://general-runtime.voiceflow.com/v4/interact"
payload = {
"action": {
"type": "launch",
"payload": { "persona": "<string>" },
"diagramID": "<string>",
"time": 123,
"metadata": {}
},
"variables": {},
"state": "<unknown>",
"config": {}
}
headers = {
"authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: {
type: 'launch',
payload: {persona: '<string>'},
diagramID: '<string>',
time: 123,
metadata: {}
},
variables: {},
state: '<unknown>',
config: {}
})
};
fetch('https://general-runtime.voiceflow.com/v4/interact', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://general-runtime.voiceflow.com/v4/interact",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => [
'type' => 'launch',
'payload' => [
'persona' => '<string>'
],
'diagramID' => '<string>',
'time' => 123,
'metadata' => [
]
],
'variables' => [
],
'state' => '<unknown>',
'config' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://general-runtime.voiceflow.com/v4/interact"
payload := strings.NewReader("{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://general-runtime.voiceflow.com/v4/interact")
.header("authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://general-runtime.voiceflow.com/v4/interact")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": {\n \"type\": \"launch\",\n \"payload\": {\n \"persona\": \"<string>\"\n },\n \"diagramID\": \"<string>\",\n \"time\": 123,\n \"metadata\": {}\n },\n \"variables\": {},\n \"state\": \"<unknown>\",\n \"config\": {}\n}"
response = http.request(request)
puts response.read_body{
"traces": [
{
"type": "audio",
"payload": {
"state": "start",
"messageID": "<string>",
"delay": 123
},
"paths": [
{
"label": "<string>",
"event": {
"type": "<string>",
"payload": "<unknown>",
"diagramID": "<string>",
"time": 123,
"metadata": {}
}
}
],
"defaultPath": 123,
"time": 123,
"turnID": "<string>",
"handleID": "<string>"
}
]
}{
"traces": [
{
"type": "audio",
"payload": {
"state": "start",
"messageID": "<string>",
"delay": 123
},
"paths": [
{
"label": "<string>",
"event": {
"type": "<string>",
"payload": "<unknown>",
"diagramID": "<string>",
"time": 123,
"metadata": {}
}
}
],
"defaultPath": 123,
"time": 123,
"turnID": "<string>",
"handleID": "<string>"
}
]
}sessionKey. Then, pass the session key as the authorization header on this endpoint to send actions and receive traces from your agent.
Each request sends an action describing what happened on the user’s side. Actions include sending a text message, selecting a button, signaling a no-reply, or continuing after a handoff. The most common are launch (to start a conversation) and text (to send a user message).
For streaming responses, use Interact (stream) instead.Authorizations
Session key returned from the start session endpoint.
Body
The user's action for this conversation turn. Most commonly, the text action is used to send a message to the agent as a user.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
Key-value pairs to set or update on the session before this turn is processed. Useful for injecting context like a user's name, account tier, or current page. Learn more.
Hide child attributes
Hide child attributes
Optional settings for this turn.
Hide child attributes
Hide child attributes
The user's IANA timezone string (eg: America/New_York). Sets {vf_user_timezone} variable. Used to localize time-dependent agent behavior.
Trace types to omit from the response, for example ["block", "debug", "flow", "path"]. Omit this field to receive every trace. A debug trace reporting credit_limit_reached is always returned, since it is what explains a 402 response.
log, end, text, path, flow, goto, speak, block, debug, choice, stream, visual, cardV2, carousel, no-reply, reasoning, completion, audio, call-forward, live-agent-handoff, entity-filling, channel-action, knowledgeBase, realtime-agent, dtmf, tool-call, simulation-test-result Response
An array of traces that occurred during this turn.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
- Option 18
- Option 19
- Option 20
- Option 21
- Option 22
- Option 23
- Option 24
- Option 25
- Option 26
Hide child attributes
Hide child attributes
audio Hide child attributes
Hide child attributes
Was this page helpful?