curl --request POST \ --url https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message \ --header 'Authorization: Bearer <token>' --header 'Content-Type: application/json' \ --data '{ "type": "generative", "examples": [ "<string>" ] }'

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Path Parameters

playbookID

string

required

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

The alias of the environment to operate on (e.g. main).

slot

object

required

Which of the tool's four messages to write. execution is said when the tool starts (the editor labels it Start), completion when it finishes (Complete), failure when it errors (Failed), delay when it is taking a while (Delayed).

Available options: delay, failure, execution, completion

toolID

string

A tool attached to this agent or playbook. Cannot be used with nativeTool.

nativeTool

object

Show child attributes

Body

A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.

Show child attributes

Option 1

Show child attributes

type

enum<string>

required

Discriminator: the model writes this message itself, guided by the examples below.

Available options: generative

examples

object[]

required

Example phrasings the model writes from. Replaces every example the slot holds today.

Option 2

Show child attributes

type

enum<string>

required

Discriminator: this message is a fixed response, said verbatim.

Available options: scripted

messageID

string

required

The ID of an existing response in this environment — the same ID this slot reports as <slot>MessageID on a read.

Response

200 - application/json

Confirms the message was set and which form, generative or scripted, the slot is now in.

message

string

required

A human-readable message confirming the update.

unresolvedReferences

object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

Show child attributes

path

string

required

Dotted path of the field that carried it, e.g. knowledgeBaseTool.filters[0].defaultValue.

token

string

required

The reference as written, without braces.

reason

enum<string>

required

unknown: no variable or entity of that name. secret-not-allowed: the name is a project secret and this field does not accept one. path-on-non-variable: only a variable has fields. resource-id: a bare resource id, not a name. invalid-name: outside the ^\w{1,64}$ name grammar. dangling: the reference rendered as a bare id, because its row is gone or its name is outside the name grammar.

Available options: unknown, secret-not-allowed, path-on-non-variable, resource-id, invalid-name, dangling

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Add playbook tool message

Authorizations

Path Parameters

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks