From 0bbae013e942911b0bd1bb776ae3a7c665988416 Mon Sep 17 00:00:00 2001 From: Ajay Raj Date: Thu, 30 Nov 2023 18:05:23 -0800 Subject: [PATCH 1/2] update openapi spec (#449) --- .../create-account-connection.mdx | 3 + .../get-account-connection.mdx | 3 + .../list-account-connections.mdx | 3 + .../update-account-connection.mdx | 3 + docs/api-reference/numbers/link-number.mdx | 3 + docs/openapi.json | 317 +++++++++++++++++- 6 files changed, 322 insertions(+), 10 deletions(-) create mode 100644 docs/api-reference/account_connections/create-account-connection.mdx create mode 100644 docs/api-reference/account_connections/get-account-connection.mdx create mode 100644 docs/api-reference/account_connections/list-account-connections.mdx create mode 100644 docs/api-reference/account_connections/update-account-connection.mdx create mode 100644 docs/api-reference/numbers/link-number.mdx diff --git a/docs/api-reference/account_connections/create-account-connection.mdx b/docs/api-reference/account_connections/create-account-connection.mdx new file mode 100644 index 000000000..b80be41ef --- /dev/null +++ b/docs/api-reference/account_connections/create-account-connection.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v1/account_connections/create +--- \ No newline at end of file diff --git a/docs/api-reference/account_connections/get-account-connection.mdx b/docs/api-reference/account_connections/get-account-connection.mdx new file mode 100644 index 000000000..58ada2502 --- /dev/null +++ b/docs/api-reference/account_connections/get-account-connection.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v1/account_connections +--- \ No newline at end of file diff --git a/docs/api-reference/account_connections/list-account-connections.mdx b/docs/api-reference/account_connections/list-account-connections.mdx new file mode 100644 index 000000000..22b3bfd2e --- /dev/null +++ b/docs/api-reference/account_connections/list-account-connections.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v1/account_connections/list +--- \ No newline at end of file diff --git a/docs/api-reference/account_connections/update-account-connection.mdx b/docs/api-reference/account_connections/update-account-connection.mdx new file mode 100644 index 000000000..1cf3289b6 --- /dev/null +++ b/docs/api-reference/account_connections/update-account-connection.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v1/account_connections/update +--- \ No newline at end of file diff --git a/docs/api-reference/numbers/link-number.mdx b/docs/api-reference/numbers/link-number.mdx new file mode 100644 index 000000000..416dce7b2 --- /dev/null +++ b/docs/api-reference/numbers/link-number.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v1/numbers/link +--- \ No newline at end of file diff --git a/docs/openapi.json b/docs/openapi.json index 0504aad6f..8b414b4d3 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1343,10 +1343,243 @@ }, "security": [{ "HTTPBearer": [] }] } + }, + "/v1/account_connections": { + "get": { + "tags": ["account_connections"], + "summary": "Get Account Connection", + "operationId": "get_account_connection", + "parameters": [ + { + "required": true, + "schema": { "type": "string", "format": "uuid", "title": "Id" }, + "name": "id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionResponseModel" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/HTTPValidationError" } + } + } + } + }, + "security": [{ "HTTPBearer": [] }] + } + }, + "/v1/account_connections/list": { + "get": { + "tags": ["account_connections"], + "summary": "List Account Connections", + "operationId": "list_account_connections", + "parameters": [ + { + "required": false, + "schema": { "type": "integer", "title": "Page", "default": 1 }, + "name": "page", + "in": "query" + }, + { + "required": false, + "schema": { "type": "integer", "title": "Size", "default": 10 }, + "name": "size", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionPage" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/HTTPValidationError" } + } + } + } + }, + "security": [{ "HTTPBearer": [] }] + } + }, + "/v1/account_connections/create": { + "post": { + "tags": ["account_connections"], + "summary": "Create Account Connection", + "operationId": "create_account_connection", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionParamsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionResponseModel" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/HTTPValidationError" } + } + } + } + }, + "security": [{ "HTTPBearer": [] }] + } + }, + "/v1/account_connections/update": { + "post": { + "tags": ["account_connections"], + "summary": "Update Account Connection", + "operationId": "update_account_connection", + "parameters": [ + { + "required": true, + "schema": { "type": "string", "format": "uuid", "title": "Id" }, + "name": "id", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionUpdateParamsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountConnectionResponseModel" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/HTTPValidationError" } + } + } + } + }, + "security": [{ "HTTPBearer": [] }] + } } }, "components": { "schemas": { + "AccountConnectionPage": { + "properties": { + "items": { + "items": { + "oneOf": [ + { "$ref": "#/components/schemas/TwilioAccountConnection" }, + { "$ref": "#/components/schemas/OpenAIAccountConnection" } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "account_connection_twilio": "#/components/schemas/TwilioAccountConnection", + "account_connection_openai": "#/components/schemas/OpenAIAccountConnection" + } + } + }, + "type": "array", + "title": "Items" + }, + "page": { "type": "integer", "title": "Page" }, + "size": { "type": "integer", "title": "Size" }, + "has_more": { "type": "boolean", "title": "Has More" } + }, + "type": "object", + "required": ["items", "page", "size", "has_more"], + "title": "AccountConnectionPage" + }, + "AccountConnectionParamsRequest": { + "oneOf": [ + { "$ref": "#/components/schemas/TwilioAccountConnectionParams" }, + { "$ref": "#/components/schemas/OpenAIAccountConnectionParams" } + ], + "title": "AccountConnectionParamsRequest", + "discriminator": { + "propertyName": "type", + "mapping": { + "account_connection_twilio": "#/components/schemas/TwilioAccountConnectionParams", + "account_connection_openai": "#/components/schemas/OpenAIAccountConnectionParams" + } + } + }, + "AccountConnectionResponseModel": { + "oneOf": [ + { "$ref": "#/components/schemas/TwilioAccountConnection" }, + { "$ref": "#/components/schemas/OpenAIAccountConnection" } + ], + "title": "AccountConnectionResponseModel", + "discriminator": { + "propertyName": "type", + "mapping": { + "account_connection_twilio": "#/components/schemas/TwilioAccountConnection", + "account_connection_openai": "#/components/schemas/OpenAIAccountConnection" + } + } + }, + "AccountConnectionUpdateParamsRequest": { + "oneOf": [ + { + "$ref": "#/components/schemas/TwilioAccountConnectionUpdateParams" + }, + { "$ref": "#/components/schemas/OpenAIAccountConnectionUpdateParams" } + ], + "title": "AccountConnectionUpdateParamsRequest", + "discriminator": { + "propertyName": "type", + "mapping": { + "account_connection_twilio": "#/components/schemas/TwilioAccountConnectionUpdateParams", + "account_connection_openai": "#/components/schemas/OpenAIAccountConnectionUpdateParams" + } + } + }, "ActionPage": { "properties": { "items": { @@ -1477,7 +1710,7 @@ }, "interrupt_sensitivity": { "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }], - "default": "high" + "default": "low" }, "context_endpoint": { "type": "string", "title": "Context Endpoint" }, "noise_suppression": { @@ -1597,7 +1830,7 @@ }, "interrupt_sensitivity": { "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }], - "default": "high" + "default": "low" }, "context_endpoint": { "type": "string", "title": "Context Endpoint" }, "noise_suppression": { @@ -2061,7 +2294,7 @@ }, "interrupt_sensitivity": { "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }], - "default": "high" + "default": "low" }, "context_endpoint": { "type": "string", "title": "Context Endpoint" }, "noise_suppression": { @@ -2434,7 +2667,7 @@ }, "interrupt_sensitivity": { "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }], - "default": "high" + "default": "low" }, "context_endpoint": { "type": "string", "title": "Context Endpoint" }, "noise_suppression": { @@ -2631,17 +2864,49 @@ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "user_id": { "type": "string", "format": "uuid", "title": "User Id" }, + "credentials": { "$ref": "#/components/schemas/OpenAICredentials" }, "type": { "type": "string", "enum": ["account_connection_openai"], "title": "Type" - }, - "credentials": { "$ref": "#/components/schemas/OpenAICredentials" } + } }, "type": "object", - "required": ["id", "user_id", "type", "credentials"], + "required": ["id", "user_id", "credentials", "type"], "title": "OpenAIAccountConnection" }, + "OpenAIAccountConnectionParams": { + "properties": { + "credentials": { "$ref": "#/components/schemas/OpenAICredentials" }, + "type": { + "type": "string", + "enum": ["account_connection_openai"], + "title": "Type" + } + }, + "type": "object", + "required": ["credentials", "type"], + "title": "OpenAIAccountConnectionParams" + }, + "OpenAIAccountConnectionUpdateParams": { + "properties": { + "credentials": { + "anyOf": [ + { "$ref": "#/components/schemas/OpenAICredentials" }, + { "$ref": "#/components/schemas/Undefined" } + ], + "title": "Credentials" + }, + "type": { + "type": "string", + "enum": ["account_connection_openai"], + "title": "Type" + } + }, + "type": "object", + "required": ["type"], + "title": "OpenAIAccountConnectionUpdateParams" + }, "OpenAICredentials": { "properties": { "openai_api_key": { "type": "string", "title": "Openai Api Key" } @@ -3081,17 +3346,49 @@ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "user_id": { "type": "string", "format": "uuid", "title": "User Id" }, + "credentials": { "$ref": "#/components/schemas/TwilioCredentials" }, "type": { "type": "string", "enum": ["account_connection_twilio"], "title": "Type" - }, - "credentials": { "$ref": "#/components/schemas/TwilioCredentials" } + } }, "type": "object", - "required": ["id", "user_id", "type", "credentials"], + "required": ["id", "user_id", "credentials", "type"], "title": "TwilioAccountConnection" }, + "TwilioAccountConnectionParams": { + "properties": { + "credentials": { "$ref": "#/components/schemas/TwilioCredentials" }, + "type": { + "type": "string", + "enum": ["account_connection_twilio"], + "title": "Type" + } + }, + "type": "object", + "required": ["credentials", "type"], + "title": "TwilioAccountConnectionParams" + }, + "TwilioAccountConnectionUpdateParams": { + "properties": { + "credentials": { + "anyOf": [ + { "$ref": "#/components/schemas/TwilioCredentials" }, + { "$ref": "#/components/schemas/Undefined" } + ], + "title": "Credentials" + }, + "type": { + "type": "string", + "enum": ["account_connection_twilio"], + "title": "Type" + } + }, + "type": "object", + "required": ["type"], + "title": "TwilioAccountConnectionUpdateParams" + }, "TwilioCredentials": { "properties": { "twilio_account_sid": { From 8827d86735f60f454b49ec46cb8ba85b55811313 Mon Sep 17 00:00:00 2001 From: Adnaan Sachidanandan Date: Thu, 30 Nov 2023 20:06:28 -0800 Subject: [PATCH 2/2] create a guide for byotk (#450) * updated hosted-api docs * updated docs with byot and byoai --- docs/bring-your-own-openai.mdx | 90 +++++++++++++++++++++++++++++++ docs/bring-your-own-telephony.mdx | 70 ++++++++++++++++++++++++ docs/mint.json | 22 ++++++-- 3 files changed, 177 insertions(+), 5 deletions(-) create mode 100644 docs/bring-your-own-openai.mdx create mode 100644 docs/bring-your-own-telephony.mdx diff --git a/docs/bring-your-own-openai.mdx b/docs/bring-your-own-openai.mdx new file mode 100644 index 000000000..7c6b0e74c --- /dev/null +++ b/docs/bring-your-own-openai.mdx @@ -0,0 +1,90 @@ +--- +title: "[Enterprise] Bring Your Own OpenAI API Keys" +description: "Use your own OpenAI keys and models with Vocode" +--- + +You can connect your own OpenAI account with Vocode. With your own OpenAI account, you can use your own OpenAI models including custom, fine-tuned models! + +***NOTE:** This feature is only enabled for users on an Enterprise plan.* + +## Step 1: Add an OpenAI account connection + +Vocode uses account connections to manage your account parameters and associate them with phone numbers and calls. You can add multiple account connections if you have multiple OpenAI accounts you would like to integrate. You can quickly add an account connection [via our API](https://api.vocode.dev/docs#/account_connections/create_account_connection) by providing an OpenAI API key. + + +```python +from vocode.client import Vocode + +vocode_client.account_connections.create_account_connection( + request={ + "type": "account_connection_openai", + "credentials": { + "openai_api_key": "YOUR_OPENAI_API_KEY", + }, + } +) +``` + +`create_account_connection` will return the parameters for your new account connection, including an `id`, which is necessary for the following steps. + +## Step 2: Use the OpenAI account connection with your agent + +To use the new account connection with your calls, you need to configure your agents with the account connection. You can do so when you create a new agent or update an existing agent via the `openai_account_connection` parameter. + + +```python Create Agent +vocode_client.agents.create_agent( + voice="...", + prompt={ + "content": "...", + }, + openai_account_connection="YOUR_ACCOUNT_CONNECTION_ID", +) +``` + +```python Update Agent +from vocode import AgentUpdateParams + +vocode_client.agents.update_agent( + id="YOUR_AGENT_ID", + request=AgentUpdateParams( + openai_account_connection="YOUR_ACCOUNT_CONNECTION_ID", + ), +) +``` + + +Any calls with this agent will now use your OpenAI account. + +### Use your own OpenAI models + +You can add your own OpenAI models to your agents using the `openai_model_name_override` parameter when creating or updating your agents. These models can be the base OpenAI models (e.g. gpt-3.5-turbo-1106, gpt-4) or your own fine-tuned models. + +***NOTE:** A model name override can only be used if you add your own OpenAI account connection to the agent. Model overrides do not work when using Vocode's OpenAI system.* + + +```python Create Agent +vocode_client.agents.create_agent( + voice="...", + prompt={ + "content": "...", + }, + openai_account_connection="YOUR_ACCOUNT_CONNECTION_ID", + openai_model_name_override="ft:your_ft_model_name" +) +``` + +```python Update Agent +from vocode import AgentUpdateParams + +vocode_client.agents.update_agent( + id="YOUR_AGENT_ID", + request=AgentUpdateParams( + openai_account_connection="YOUR_ACCOUNT_CONNECTION_ID", # if not already updated + openai_model_name_override="gpt-4-1106-preview" + ), +) +``` + + +Now, your Vocode calls with this agent will use your own OpenAI account and your own OpenAI models! diff --git a/docs/bring-your-own-telephony.mdx b/docs/bring-your-own-telephony.mdx new file mode 100644 index 000000000..8cb3e0c88 --- /dev/null +++ b/docs/bring-your-own-telephony.mdx @@ -0,0 +1,70 @@ +--- +title: "[Enterprise] Bring Your Own Telephony" +description: "Use your own Twilio account and phone numbers with Vocode" +--- + +You can connect your own external Twilio accounts with Vocode, enabling you to send and receive calls on your own phone numbers and store recordings in your Twilio account. + +***NOTE:** This feature is only enabled for users on an Enterprise plan.* + +## Step 1: Add a Twilio account connection + +Vocode uses account connections to manage your account parameters and associate them with phone numbers and calls. You can add multiple account connections if you have multiple Twilio accounts you would like to integrate. You can quickly add an account connection [via our API](https://api.vocode.dev/docs#/account_connections/create_account_connection) by providing your account SID and an auth token. + + +```python +from vocode.client import Vocode + +vocode_client.account_connections.create_account_connection( + request={ + "type": "account_connection_twilio", + "credentials": { + "twilio_account_sid": "YOUR_ACCOUNT_SID", + "twilio_auth_token": "YOUR_AUTH_TOKEN", + }, + } +) +``` + +`create_account_connection` will return the parameters for your new account connection, including an `id`, which is necessary for the following steps. + +## Step 2: Link existing Twilio numbers to Vocode + +Vocode now can make calls with your Twilio account, but our system needs to know which numbers to configure and use. We provide the `/v1/numbers/link` [endpoint](https://api.vocode.dev/docs#/numbers/link_number) to add these numbers to our system. You simply need to provide the phone number, your account connection id, and whether or not the phone number should be outbound only. + +```python Python +vocode_client.numbers.link_number( + phone_number="1234567890", + telephony_account_connection="YOUR_ACCOUNT_CONNECTION_ID", + outbound_only=True +) +``` + +You can now use this phone number for outbound calls (and inbound if you have it configured). + + +## Step 3: View your call objects + +After making a call with your newly added number, you can see two new fields in your call object: +- **Telephony Account Connection:** The account connection object associated with the call +- **Telephony ID:** The Twilio call SID corresponding to the Vocode call + +```json +{ + id: 'call_id', + userId: 'user_id', + toNumber: '123456789', + fromNumber: '123456789', + ... + telephonyId: 'telephony_id', + telephonyAccountConnection: { + 'id': 'account_connection_id', + 'user_id': 'user_id', + 'credentials': { + 'twilio_account_sid': 'YOUR_TWILIO_ACCOUNT_SID', + 'twilio_auth_token': 'YOUR_TWILIO_AUTH_TOKEN' + }, + 'type': 'account_connection_twilio' + } +} +``` diff --git a/docs/mint.json b/docs/mint.json index 37518f38f..2e0d0bc20 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -49,11 +49,19 @@ "navigation": [ { "group": "Getting Started", - "pages": ["welcome", "hosted-quickstart", "open-source-quickstart"] + "pages": [ + "welcome", + "hosted-quickstart", + "open-source-quickstart" + ] }, { "group": "Vocode 101", - "pages": ["what-is-vocode", "how-it-works", "how-to-use-it"] + "pages": [ + "what-is-vocode", + "how-it-works", + "how-to-use-it" + ] }, { "group": "Guides", @@ -105,7 +113,9 @@ }, { "group": "Usage", - "pages": ["api-reference/usage/get-usage"] + "pages": [ + "api-reference/usage/get-usage" + ] }, { "group": "Actions", @@ -175,7 +185,9 @@ "machine-detection", "ivr-navigation", "hipaa-compliance", - "do-not-call-detection" + "do-not-call-detection", + "bring-your-own-telephony", + "bring-your-own-openai" ] } ], @@ -188,4 +200,4 @@ "twitter": "https://twitter.com/vocodehq", "website": "https://www.vocode.dev/" } -} +} \ No newline at end of file