Merge pull request #9 from dimagi/sk/custom-actions

Docs for custom actions and auth providers

docs/conceptual_guide/custom_actions.md

@@ -0,0 +1,36 @@
+# Custom Actions
+
+Custom Actions enable bots to communicate with external services via HTTP API calls. 
+This feature allows you to extend the functionality of your bot by integrating it with other services.
+
+This feature is analogous to the OpenAI's [GPT Actions](https://platform.openai.com/docs/actions/introduction) feature.
+
+## Custom Action Fields
+
+### Authentication Provider
+
+Before you create a Custom Action will need to create an Authentication Provider for your action to use (unless the API
+you are using does not require authentication). You can do this by navigating to the [Authentication Providers][auth_providers] section
+in Team Settings and creating a new Authentication Provider.
+
+[auth_providers]: ../team-configuration/authentication-providers.md
+
+### Base URL
+
+This is the URL of the external service you want to communicate with. For example: `https://www.example.com`. Only HTTPS URLs
+are supported.
+
+### API Schema
+
+This is a JSON or YAML [OpenAPI Schema](https://swagger.io/specification/) document.
+
+You should be able to get this from the service you want to connect to. For example, the default location for the schema for [FastAPI](https://fastapi.tiangolo.com/) services is `/openapi.json` (https://fastapi.tiangolo.com/tutorial/first-steps/#openapi-and-json-schema).
+
+## How Custom Actions work
+
+When you create a custom action, each API endpoint in the OpenAPI schema will be available as a separate action in the
+Experiment configuration. This gives you full control over which actions are available to your bot.
+
+When you add a Custom Action to your Experiment, the bot will be able to make HTTP requests to the external service
+using the API endpoints you have configured. The bot will send the request and receive the response from the external
+service, which it can then use to generate a response to the user.

docs/how-to/add_a_knowledge_base.md

@@ -33,4 +33,4 @@ To add knowldege to your assistant, you must upload files to serve as the source
 [prompt_variables_concept]: ../conceptual_guide/prompt_variables.md
 [assistants]: https://platform.openai.com/docs/assistants/overview
 [file_search]: https://platform.openai.com/docs/assistants/tools/file-search
-[code_interpreter]: https://platform.openai.com/docs/assistants/tools/code-interpreter
+[code_interpreter]: https://platform.openai.com/docs/assistants/tools/code-interpreter

docs/how-to/remote_api.md

@@ -0,0 +1,23 @@
+# Connecting to a remote API
+
+Open Chat Studio allows you to connect to external services via HTTP API calls. This feature is useful for extending the functionality of your bot by integrating it with other services. This feature is analogous to OpenAI's [GPT Actions](https://platform.openai.com/docs/actions/introduction) feature.
+
+To do this you will need to create a Custom Action by navigating to the [Authentication Providers](../team-configuration/authentication-providers.md) section in Team Settings. See the [Custom Actions](../conceptual_guide/custom_actions.md) guide for more information on how to create a Custom Action.
+
+## Using the custom action in your bot
+
+Once you have created a custom action you can add it to your bot by following these steps:
+
+1. Open your Experiment's edit page.
+2. Navigate to the *Tools* tab.
+3. Select the action you want to add from the *Custom Actions* checkbox list.
+
+## Testing the custom action
+
+To test the custom action, you can open a chat with your Experiment and type a message that triggers the action. The bot will make an HTTP request to the external service and return the response to you.
+
+To see more detail about the request and response, you can enable tracing in the *Advanced* tab of your Experiment.
+
+<!---
+TODO: add a link to the tracing docs
+-->

docs/team-configuration/authentication-providers.md

@@ -0,0 +1,31 @@
+# Authentication Providers
+
+Authentication Providers are used to authenticate with external services via HTTP API calls. Authentication Providers
+provide a centralized location to manage the credentials and tokens required to authenticate with external services.
+
+These credentials are used by features like [Custom Actions](/conceptual_guide/custom_actions/).
+
+## Authentication Provider Types
+
+Open Chat Studio supports various different authentication types. You should select the type that matches the API
+service you will be using.
+
+### Basic Auth
+
+Basic Auth is a simple authentication scheme built into the HTTP protocol.
+
+### API Key
+
+API Key is a simple authentication scheme that involves sending a key with the request to authenticate the user. The key
+is sent in a header of the request. The name of the header can be customized when creating the Authentication Provider.
+
+### Bearer Token
+
+Bearer Token is a type of access token that is sent with the request to authenticate the user. The token is sent in the
+Authorization header of the request.
+
+### CommCare
+
+[CommCare HQ](https://www.commcarehq.org/) uses a custom authentication scheme as described in the [CommCare Documentation][1]
+
+[1]: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2279637003/CommCare+API+Overview#API-Key-authentication