Have your agent communicate with an External API
description
and input_schema
!
input_schema
Fieldinput_schema
field is a JSON Schema object that instructs how to properly form a payload to send to the External API.
For example, in the Meeting Assistant Example below we formed the following JSON payload:
length
(string): either “30m” or “1hr”time
(string): a regex pattern defining a time ending in a zero with am
/pm
on the end ie: 10:30am
input_schema
JSON schema must be an object
- this is so we can use JSON to send over parameters to the user’s API.description
Fielddescription
is best used to descibe your External Action’s purpose. As its passed through directly to the LLM, its the best way to convey instructions to the underlying Vocode Agent.
For example, in the Meeting Assistant Example below we want to book a meeting for 30 minutes to an hour so we set the description as Book a meeting for a 30 minute or 1 hour call.
description
field is passed through and heavily affects how we do our
function decisioning so we recommend treating it in the same way you would a
prompt to an LLM!speak_on_send
: if True
, then the underlying LLM will generate a message to be spoken into the phone call as the
API request is being sent. - url
: The API request is sent to this URL in the format
defined below in Responding to External Action API Requests
speak_on_receive
: if True
, then the Vocode Agent will invoke the underlying
LLM to respond based on the result from the API Response or the Error encountered.
url
during the course of a phone call based on the configuration noted above
The Vocode API will wait a maximum of 10 seconds before timing out the request.
In particular, Vocode will issue a POST request to url
with a JSON payload that matches input_schema
, specifically (using the Meeting Assistant Example below):
x-vocode-signature
) in the outbound request so that the user’s API can validate the identity of the incoming request.
The signature secret is contained in the External Action’s API object and can be found when creating an object (as noted below in the Meeting Assistant Example), or by getting the API object via the /v1/actions?id=ACTION_ID
endpoint:
result
is a payload containing the result of the action on the user’s side, and can have any schemaagent_message
optionally contains a message that will be synthesized into audio and sent back to the phone call (see Configuring the External Action above for more info)