diff --git a/fern/docs.yml b/fern/docs.yml index a485009ae..09577e1d1 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -224,6 +224,8 @@ navigation: path: tools/api-request/quickstart.mdx - page: Customize requests path: tools/api-request/configuration.mdx + - page: Get order status + path: tools/api-request/order-status.mdx - page: Handle latency and retries path: tools/api-request/reliability.mdx - page: Handle responses and errors diff --git a/fern/static/images/tools/api-request/02-request-body.png b/fern/static/images/tools/api-request/02-request-body.png index 8e677e118..2ab22809e 100644 Binary files a/fern/static/images/tools/api-request/02-request-body.png and b/fern/static/images/tools/api-request/02-request-body.png differ diff --git a/fern/static/images/tools/api-request/11-order-status-request-body.png b/fern/static/images/tools/api-request/11-order-status-request-body.png new file mode 100644 index 000000000..ab0f697b5 Binary files /dev/null and b/fern/static/images/tools/api-request/11-order-status-request-body.png differ diff --git a/fern/static/images/tools/api-request/12-attached-order-tools.png b/fern/static/images/tools/api-request/12-attached-order-tools.png new file mode 100644 index 000000000..d7869d466 Binary files /dev/null and b/fern/static/images/tools/api-request/12-attached-order-tools.png differ diff --git a/fern/tools/api-request/order-status.mdx b/fern/tools/api-request/order-status.mdx new file mode 100644 index 000000000..96f996abc --- /dev/null +++ b/fern/tools/api-request/order-status.mdx @@ -0,0 +1,278 @@ +--- +title: Get order status +subtitle: Extend the coffee-order assistant so callers can check an existing order on a later call +description: Add an order-status API Request Tool to the coffee-order assistant, update its opening and system prompt, and verify status lookup across two inbound calls. +slug: tools/api-request/order-status +--- + +Extend the configured coffee-order assistant with a second API Request Tool that looks up an order by its five-digit order number. This guide keeps `createCoffeeOrder` and its request configuration unchanged. You update the existing assistant and keep its connected phone number. + +## Prerequisites + +- The coffee-order assistant and `createCoffeeOrder` tool from the [quickstart](/tools/api-request/quickstart) +- The request configuration from [Customize API Request tool requests](/tools/api-request/configuration) +- For cURL, your Vapi API key, the existing tool ID, and the assistant ID from the quickstart + +## 1. Create the status tool + +Create one new API Request Tool named `getCoffeeOrderStatus`. Keep the existing `createCoffeeOrder` tool and any request configuration you already added to it. + + + + + + Open the [Dashboard](https://dashboard.vapi.ai), select **Tools**, select **Create Tool**, then choose **API Request**. + + + + Enter these values under **Base Configuration**: + + | Field | Value | + | --- | --- | + | **Tool Name** | `getCoffeeOrderStatus` | + | **Description** | `Gets the status of a mock coffee shop order. Use only after the caller states and confirms a five-digit order number. Never guess an order number or status.` | + | **Request URL** | `https://vapi-docs-orders.val.run/lookup` | + | **Request HTTP Method** | `POST` | + + Under **Authorization**, keep **No authentication** selected. + + + + Under **Request Body**, add one required property: + + | Property | Type | Required | Configuration | + | --- | --- | --- | --- | + | `orderId` | Number | Yes | Description: `The five-digit whole-number order ID stated and confirmed by the caller.` | + + Leave **Default value** empty. The Dashboard exposes this property as **Number**; the endpoint still requires a whole number from `10000` through `99999`. + + Select **Apply**, enable **Lock schema (no additional properties)**, then select **Publish**. + + + Vapi Dashboard Request Body with orderId as the only required property + + + + + + + Create a second tool with the [Create Tool endpoint](/api-reference/tools/create). Reuse the `VAPI_API_KEY` from the earlier guides; do not replace the existing `VAPI_TOOL_ID` value. + + ```bash + curl --request POST \ + --url https://api.vapi.ai/tool \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "type": "apiRequest", + "name": "getCoffeeOrderStatus", + "description": "Gets the status of a mock coffee shop order. Use only after the caller states and confirms a five-digit order number. Never guess an order number or status.", + "method": "POST", + "url": "https://vapi-docs-orders.val.run/lookup", + "timeoutSeconds": 20, + "body": { + "type": "object", + "properties": { + "orderId": { + "type": "integer", + "minimum": 10000, + "maximum": 99999, + "description": "The five-digit order number stated and confirmed by the caller." + } + }, + "required": ["orderId"], + "additionalProperties": false + } + }' + ``` + + Copy the returned `id`, then export both tool IDs: + + ```bash + export VAPI_TOOL_ID="YOUR_CREATE_COFFEE_ORDER_TOOL_ID" + export VAPI_STATUS_TOOL_ID="RETURNED_STATUS_TOOL_ID" + ``` + + + +Do not copy the headers, static body fields, or credential from `createCoffeeOrder`. The status endpoint needs only `orderId`. + +## 2. Extend the existing assistant + +Replace the assistant's complete **System Prompt** with the prompt below. It includes the existing product and order instructions plus the new status flow, so do not append it to the old prompt. + +```txt title="System prompt" wordWrap +You are a friendly coffee shop assistant. Help callers place an order or check the status of an existing order. + +Available products: +- House coffee beans: productId coffee-beans, $18 each +- Tea sampler: productId tea-sampler, $14 each +- Ceramic mug: productId ceramic-mug, $12 each + +Ask one question at a time and keep responses concise. Use tool results to answer naturally. Do not read product IDs, internal field names, the internal requestId, or raw tool responses aloud. + +To place an order, collect the caller's name, product, and positive whole-number quantity. If the caller requests an unavailable product, say it is unavailable and offer the listed products. Never substitute another product without confirmation. + +Read back the caller's name, product, quantity, and listed unit price, then get explicit confirmation before calling createCoffeeOrder. Never invent a productId, and never call createCoffeeOrder before confirmation. + +After a successful createCoffeeOrder response, confirm the product, quantity, and server-calculated total. Read the five-digit order number one digit at a time and tell the caller to save it for a later status check. If createCoffeeOrder fails, do not claim that the order was created or invent an order number or total. + +To check order status, collect the five-digit order number. Do not collect the caller's name, product, or quantity, and do not call createCoffeeOrder. Read the order number back one digit at a time and get explicit confirmation before calling getCoffeeOrderStatus. Never guess or complete a partial number. + +After a successful getCoffeeOrderStatus response, state the returned order number and communicate the returned statusLabel naturally. If the first lookup finds no order, reconfirm the number and try once more. If no order is found after the second confirmed lookup, apologize, state that the order could not be located, and do not retry again for that request. For any other error, say you could not retrieve the status. Do not guess. + +After completing a request, do not reuse its collected name, product, quantity, or order number. If the caller starts another order or status check, collect and confirm the required information again. + +After completing the caller's request, ask whether they need anything else. If they do not, say "Thanks for calling. Goodbye." Do not continue speaking after that sentence. +``` + + + + + + Open `Docs Coffee Order Hello World` and update these fields: + + | Field | Value | + | --- | --- | + | **First Message** | `Thanks for calling the Vapi coffee shop. Would you like to place an order or check an existing order?` | + | **System Prompt** | Replace the complete prompt with the system prompt above. | + + Keep the assistant's existing end-call settings, other settings, and connected phone number. Do not create another assistant. + + + + In **Tools**, add `getCoffeeOrderStatus` and keep `createCoffeeOrder` attached. + + + Vapi Dashboard assistant Tools section with createCoffeeOrder and getCoffeeOrderStatus attached + + + + + Select **Publish**, review the changes, then select **Quick Publish**. The existing phone number remains connected to this assistant. + + + + + + Keep `VAPI_API_KEY`, `VAPI_TOOL_ID`, and `VAPI_STATUS_TOOL_ID` set from the earlier cURL steps. Replace `YOUR_ASSISTANT_ID` with the assistant ID from the quickstart, then run this command. It requires `jq`. + + The command retrieves the complete existing model, replaces the first system message, and adds both tool IDs. It preserves the provider, model, temperature, any additional messages, and existing tool IDs. + + ```bash title="Update the existing assistant" wordWrap + ( + set -euo pipefail + + VAPI_ASSISTANT_ID="YOUR_ASSISTANT_ID" + : "${VAPI_API_KEY:?Set VAPI_API_KEY before running this command}" + : "${VAPI_TOOL_ID:?Set VAPI_TOOL_ID to the createCoffeeOrder tool ID}" + : "${VAPI_STATUS_TOOL_ID:?Set VAPI_STATUS_TOOL_ID to the getCoffeeOrderStatus tool ID}" + + FIRST_MESSAGE='Thanks for calling the Vapi coffee shop. Would you like to place an order or check an existing order?' + SYSTEM_PROMPT=$(cat <<'PROMPT' + You are a friendly coffee shop assistant. Help callers place an order or check the status of an existing order. + + Available products: + - House coffee beans: productId coffee-beans, $18 each + - Tea sampler: productId tea-sampler, $14 each + - Ceramic mug: productId ceramic-mug, $12 each + + Ask one question at a time and keep responses concise. Use tool results to answer naturally. Do not read product IDs, internal field names, the internal requestId, or raw tool responses aloud. + + To place an order, collect the caller's name, product, and positive whole-number quantity. If the caller requests an unavailable product, say it is unavailable and offer the listed products. Never substitute another product without confirmation. + + Read back the caller's name, product, quantity, and listed unit price, then get explicit confirmation before calling createCoffeeOrder. Never invent a productId, and never call createCoffeeOrder before confirmation. + + After a successful createCoffeeOrder response, confirm the product, quantity, and server-calculated total. Read the five-digit order number one digit at a time and tell the caller to save it for a later status check. If createCoffeeOrder fails, do not claim that the order was created or invent an order number or total. + + To check order status, collect the five-digit order number. Do not collect the caller's name, product, or quantity, and do not call createCoffeeOrder. Read the order number back one digit at a time and get explicit confirmation before calling getCoffeeOrderStatus. Never guess or complete a partial number. + + After a successful getCoffeeOrderStatus response, state the returned order number and communicate the returned statusLabel naturally. If the first lookup finds no order, reconfirm the number and try once more. If no order is found after the second confirmed lookup, apologize, state that the order could not be located, and do not retry again for that request. For any other error, say you could not retrieve the status. Do not guess. + + After completing a request, do not reuse its collected name, product, quantity, or order number. If the caller starts another order or status check, collect and confirm the required information again. + + After completing the caller's request, ask whether they need anything else. If they do not, say "Thanks for calling. Goodbye." Do not continue speaking after that sentence. + PROMPT + ) + + CURRENT_ASSISTANT=$(curl --fail --silent --show-error \ + --url "https://api.vapi.ai/assistant/$VAPI_ASSISTANT_ID" \ + --header "Authorization: Bearer $VAPI_API_KEY") + + PATCH_BODY=$(printf '%s' "$CURRENT_ASSISTANT" | jq -e \ + --arg firstMessage "$FIRST_MESSAGE" \ + --arg prompt "$SYSTEM_PROMPT" \ + --arg orderToolId "$VAPI_TOOL_ID" \ + --arg statusToolId "$VAPI_STATUS_TOOL_ID" \ + '{ + firstMessage: $firstMessage, + model: ( + .model + | if ((.messages | type) != "array" or (.messages | length) == 0 or .messages[0].role != "system") + then error("Expected model.messages[0] to be the existing system message") + else .messages[0].content = $prompt + end + | .toolIds = ( + reduce (((.toolIds // []) + [$orderToolId, $statusToolId])[]) as $id + ([]; if index($id) == null then . + [$id] else . end) + ) + ) + }') + + printf '%s' "$PATCH_BODY" | + curl --fail-with-body --silent --show-error \ + --request PATCH \ + --url "https://api.vapi.ai/assistant/$VAPI_ASSISTANT_ID" \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data-binary @- | + jq '{id, firstMessage, toolIds: .model.toolIds}' + ) + ``` + + + +## 3. Test two calls + + + + Call the connected phone number and follow the [quickstart test flow](/tools/api-request/quickstart#5-place-a-coffee-order). Save the five-digit order number the assistant reads back. + + + + The endpoint calculates the order status from the time the order was created: + + | Time since creation | Status | + | --- | --- | + | Less than 30 seconds | `confirmed` | + | 30 to less than 90 seconds | `preparing` | + | 90 seconds or more | `ready_for_pickup` | + + + + Call the same phone number and ask for the order's status. Provide the saved order number and confirm it when the assistant reads the digits back. + + The assistant should call `getCoffeeOrderStatus` and state the returned `statusLabel`. The returned `status` should match the time window above. + + + +A ready order returns these values: + +```json +{ + "orderId": 47730, + "status": "ready_for_pickup", + "statusLabel": "Order is ready for pickup" +} +``` + +## Next steps + + + + Design response contracts and help the assistant recover from failures. + + + Extract response values and pass them to later tools. + + diff --git a/fern/tools/api-request/quickstart.mdx b/fern/tools/api-request/quickstart.mdx index 6f30ca240..7fca68a57 100644 --- a/fern/tools/api-request/quickstart.mdx +++ b/fern/tools/api-request/quickstart.mdx @@ -34,7 +34,7 @@ curl --request POST \ }' ``` -The endpoint returns an HTTP `201` response. The `requestId` and five-digit `orderId` change with every request. +The endpoint returns an HTTP `201` response with a new `requestId` and a randomly generated five-digit `orderId`. ```json { @@ -73,9 +73,6 @@ The endpoint returns an HTTP `201` response. The `requestId` and five-digit `ord Under **Authorization**, keep **No authentication** selected. This public endpoint is for testing only. - - Vapi Dashboard Base Configuration for the createCoffeeOrder API Request Tool - @@ -171,7 +168,7 @@ Help the caller place one order. Collect their name, product, and positive whole After a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud. -After confirming a successful order, ask whether the caller needs anything else. If they do not, say "Thanks for your order. Goodbye." Do not continue speaking after that closing sentence. +After confirming a successful order, ask whether the caller needs anything else. If they do not, say "Thanks for calling. Goodbye." Do not continue speaking after that closing sentence. ``` @@ -190,27 +187,17 @@ After confirming a successful order, ask whether the caller needs anything else. Select OpenAI **GPT-4o Mini Cluster** as the model and Vapi **Clara v2** as the voice. Replace **System Prompt** with the prompt above. - - Vapi Dashboard assistant editor with the coffee-order first message and system prompt - In the assistant's **Tools** section, add `createCoffeeOrder`. - - Vapi Dashboard assistant Tools section with createCoffeeOrder attached - - In the assistant editor, set **End Call Message** to `Thanks for your order. Goodbye.` Then add `Thanks for your order` to **End Call Phrases**. + In the assistant editor, set **End Call Message** to `Thanks for calling. Goodbye.` Then add `Thanks for calling. Goodbye.` to **End Call Phrases**. - Only the assistant's speech triggers an end call phrase. The phrase omits punctuation so it still matches the closing sentence in the system prompt. - - - Vapi Dashboard End Call Message and End Call Phrases configured for the coffee-order assistant - + Only the assistant's speech triggers an end call phrase. Using the complete closing sentence keeps the phrase from matching the assistant's opening. @@ -221,40 +208,47 @@ After confirming a successful order, ask whether the caller needs anything else. + + Replace `YOUR_TOOL_ID` with the tool ID returned in the previous section, then save the following as `coffee-order-assistant.json`: + + ```json title="coffee-order-assistant.json" wordWrap + { + "name": "Docs Coffee Order Hello World", + "firstMessage": "Thanks for calling the Vapi coffee shop. What would you like to order?", + "model": { + "provider": "openai", + "model": "gpt-4o-mini", + "toolIds": ["YOUR_TOOL_ID"], + "messages": [ + { + "role": "system", + "content": "You are a friendly coffee shop order assistant.\n\nAvailable products:\n- House coffee beans: productId coffee-beans, $18 each\n- Tea sampler: productId tea-sampler, $14 each\n- Ceramic mug: productId ceramic-mug, $12 each\n\nHelp the caller place one order. Collect their name, product, and positive whole-number quantity. Read the complete order back and get explicit confirmation before calling createCoffeeOrder. Never invent a productId and never call the tool before confirmation.\n\nAfter a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud.\n\nAfter confirming a successful order, ask whether the caller needs anything else. If they do not, say \"Thanks for calling. Goodbye.\" Do not continue speaking after that closing sentence." + } + ], + "temperature": 0.2 + }, + "voice": { + "provider": "vapi", + "voiceId": "Clara", + "version": "latest" + }, + "endCallMessage": "Thanks for calling. Goodbye.", + "endCallPhrases": ["Thanks for calling. Goodbye."] + } + ``` + + - Replace `YOUR_TOOL_ID` with the tool ID returned in the previous section, then send the request to the [Create Assistant endpoint](/api-reference/assistants/create). + Set `VAPI_API_KEY` to your Vapi API key, then send the file to the [Create Assistant endpoint](/api-reference/assistants/create): ```bash - curl --request POST \ - --url https://api.vapi.ai/assistant \ + curl --fail-with-body https://api.vapi.ai/assistant \ --header "Authorization: Bearer $VAPI_API_KEY" \ --header "Content-Type: application/json" \ - --data '{ - "name": "Docs Coffee Order Hello World", - "firstMessage": "Thanks for calling the Vapi coffee shop. What would you like to order?", - "model": { - "provider": "openai", - "model": "gpt-4o-mini", - "toolIds": ["YOUR_TOOL_ID"], - "messages": [ - { - "role": "system", - "content": "You are a friendly coffee shop order assistant.\n\nAvailable products:\n- House coffee beans: productId coffee-beans, $18 each\n- Tea sampler: productId tea-sampler, $14 each\n- Ceramic mug: productId ceramic-mug, $12 each\n\nHelp the caller place one order. Collect their name, product, and positive whole-number quantity. Read the complete order back and get explicit confirmation before calling createCoffeeOrder. Never invent a productId and never call the tool before confirmation.\n\nAfter a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud.\n\nAfter confirming a successful order, ask whether the caller needs anything else. If they do not, say \"Thanks for your order. Goodbye.\" Do not continue speaking after that closing sentence." - } - ], - "temperature": 0.2 - }, - "voice": { - "provider": "vapi", - "voiceId": "Clara", - "version": "latest" - }, - "endCallMessage": "Thanks for your order. Goodbye.", - "endCallPhrases": ["Thanks for your order"] - }' + --data-binary @coffee-order-assistant.json ``` - Copy the `id` from the response. You will use it as `YOUR_ASSISTANT_ID` when you connect the phone number. + Copy the `id` from the response. You will use it as `YOUR_ASSISTANT_ID` when you extend the assistant in [Get order status](/tools/api-request/order-status).