# Assistant Conversation Logs
Source: https://doc.rapida.ai/activity/conversation-logs

Monitor and improve your AI assistant interactions in Rapida

Assistant Conversation Logs in Rapida help you track, analyze, and enhance your AI-powered conversations. This guide will show you how to use this feature effectively to improve your assistant's performance.

## Accessing Conversation Logs

1. Log in to your Rapida dashboard
2. Navigate to the "Logs" section in the sidebar
3. Select "Conversation" from the logs menu

## Understanding the Log Overview

<Frame>
  <img alt="Conversation Logs Overview Table" />
</Frame>

The log table provides key information at a glance:

* **ID**: Unique conversation identifier
* **Session ID**: Groups related interactions
* **Assistant ID**: Your AI assistant's identifier
* **Source**: Where the conversation originated (e.g., Debugger, React SDK)
* **Request/Response**: Quick view of user inputs and AI responses
* **Created Date**: When the interaction occurred
* **Status**: Current conversation state
* **Time Taken**: Response generation time

## Analyzing Individual Conversations

1. Click on any log entry to view full details
2. Review the complete conversation flow
3. Check for any unexpected responses or errors
4. Use this information to refine your assistant's knowledge or responses

## Leveraging Conversation Telemetry

<Frame>
  <img alt="Conversation Telemetry" />
</Frame>

The Telemetry tab breaks down processing time for each interaction:

1. Navigate to the Telemetry tab for a selected conversation
2. Identify which stages (e.g., Request, Response, Text Generation) take the most time
3. Use this data to optimize your assistant's performance:
   * If 'Text Generation' is slow, consider simplifying complex prompts
   * High 'Request' times might indicate issues with user input processing

## Practical Tips for Rapida Users

1. **Regular Log Reviews**:

   * Set a weekly reminder to review your latest conversation logs
   * Look for patterns in user queries and assistant responses

2. **Performance Optimization**:

   * Use the Time Taken column to identify slow interactions
   * Investigate and optimize the slowest 10% of your conversations

3. **Improve Assistant Accuracy**:

   * Note common misunderstandings or incorrect responses
   * Update your assistant's training data or prompts based on these findings

4. **Enhance User Experience**:

   * Look for conversations where users ask for clarification
   * Refine your assistant's responses to be more clear and helpful

5. **Debug Issues Quickly**:

   * When users report problems, use Session IDs to locate specific conversations
   * Analyze the full interaction to understand what went wrong

6. **Monitor New Deployments**:
   * After updating your assistant, closely watch logs for any changes in performance or accuracy
   * Compare Time Taken metrics before and after updates

## Taking Action on Insights

<CardGroup>
  <Card title="Refine Training Data" icon="database">
    Use common user queries from logs to expand your assistant's knowledge base.
  </Card>

  <Card title="Optimize Response Times" icon="brain">
    If telemetry shows slow responses, consider caching frequent queries or
    simplifying complex logic.
  </Card>

  <Card title="Improve Conversation Flow" icon="route">
    Identify where users often get stuck and add proactive guidance in those
    areas.
  </Card>

  <Card title="Enhance Error Handling" icon="shield-check">
    Look for 'error' statuses in logs and implement better fallback responses.
  </Card>
</CardGroup>

By actively using the Conversation Logs, you'll gain valuable insights to continuously improve your AI assistant's performance and user satisfaction on the Rapida platform.


# LLM Logs
Source: https://doc.rapida.ai/activity/llm-logs

Monitor and analyze Language Model (LLM) interactions in the Rapida platform

The LLM Logs feature provides detailed information about Language Model (LLM) requests and responses, allowing you to monitor and analyze the performance and behavior of LLM interactions within your system.

## Log Overview

<Frame>
  <img alt="LLM Logs Overview Table" />
</Frame>

The main log view displays a table with the following columns:

* **Source**: Unique identifier for each log entry
* **Provider Name**: The LLM provider (e.g., azure-openai)
* **Model Name**: The specific model used (e.g., gpt-4.1-nano)
* **Created Date**: Timestamp of when the request was made
* **Status**: Current status of the request (e.g., Complete)
* **Time Taken**: Processing time for the request
* **HTTP Status**: Response status code (e.g., 200 for success)

## Detailed Log Entry

Clicking on a log entry reveals more detailed information, divided into several tabs:

### Metadata

<Frame>
  <img alt="LLM Logs Metadata Tab" />
</Frame>

Key performance indicators and request details:

* **LLM\_REQUEST\_ID**: Unique identifier for the request
* **STATUS**: Outcome of the request (e.g., SUCCESS)
* **OUTPUT\_TOKEN**: Number of tokens in the output
* **INPUT\_TOKEN**: Number of tokens in the input
* **TOTAL\_TOKEN**: Total tokens used in the request
* **TIME\_TAKEN**: Processing time in milliseconds

### Request

<Frame>
  <img alt="LLM Logs Request Tab" />
</Frame>

Contains the original prompt and configuration sent to the LLM:

* **frequency\_penalty**: Adjusts the model's likelihood to repeat itself
* **max\_tokens**: Maximum number of tokens the model can generate
* **messages**: The input prompt and any context provided

### Response

<Frame>
  <img alt="LLM Logs Response Tab" />
</Frame>

Shows the LLM's output and related metadata:

* **finish\_reason**: Why the LLM stopped generating (e.g., "stop")
* **index**: Position of the response in case of multiple outputs
* **content**: The actual text generated by the LLM

### Metrics

<Frame>
  <img alt="LLM Logs Metrics Tab" />
</Frame>

Provides additional metadata about the request:

* **Status**: Final status of the request
* **Time Taken**: Processing duration
* **Request Created Time**: When the request was initiated
* **Response Body**: HTTP status of the response
* **Endpoint Id**: Identifier for the LLM endpoint used
* **Model Id**: Identifier for the specific model
* **Provider Name**: Name of the LLM service provider
* **Vault Id**: Security-related identifier

## Using LLM Logs

1. **Performance Monitoring**: Track response times and token usage to optimize your LLM integration.
2. **Debugging**: Investigate failed requests or unexpected outputs by examining the full request and response details.
3. **Quality Assurance**: Review LLM responses to ensure they meet your application's standards.
4. **Cost Management**: Monitor token usage to manage expenses related to LLM API calls.

## Use Cases

<CardGroup>
  <Card title="Optimize Prompts" icon="brain">
    Analyze input-output pairs to refine your prompts for better results and
    efficiency.
  </Card>

  <Card title="Troubleshoot Errors" icon="bug">
    Quickly identify and resolve issues by examining detailed error logs and
    response data.
  </Card>

  <Card title="Track Performance" icon="trending-up">
    Monitor response times and token usage to ensure optimal system performance.
  </Card>

  <Card title="Ensure Compliance" icon="shield-check">
    Review LLM interactions to maintain compliance with internal policies and
    external regulations.
  </Card>
</CardGroup>


# Webhook Logs
Source: https://doc.rapida.ai/activity/webhook-logs

Monitor and analyze webhook interactions in the Rapida platform

The Webhook Logs feature provides detailed information about webhook requests and responses, allowing you to monitor and analyze the performance and behavior of webhook interactions within your system.

## Log Overview

<Frame>
  <img alt="Webhook Logs Overview Table" />
</Frame>

The main log view displays a table with the following columns:

* **Webhook ID**: Unique identifier for each webhook
* **Session ID**: Identifier for the session associated with the webhook
* **Event**: Type of event, such as `call.received`, `call.ringing`, `call.ended`, `webrtc.connected`, `webrtc.reconnecting`, `conversation.begin`, `conversation.completed`, or `conversation.error`
* **Endpoint**: The URL endpoint where the webhook is sent
* **HTTP Status**: Response status code (e.g., 200 for success)
* **Time Taken**: Processing time for the request in milliseconds
* **Retry Count**: Number of retry attempts, if any
* **Created Date**: Timestamp of when the webhook was triggered

## Detailed Log Entry

Clicking on a log entry reveals more detailed information, divided into two tabs:

### Request

<Frame>
  <img alt="Webhook Logs Request Tab" />
</Frame>

Contains the JSON payload sent to your webhook endpoint:

* **event**: Event name that triggered delivery.
* **assistant**: Assistant context, including the assistant ID.
* **conversation**: Conversation context, including the conversation ID when available.
* **data**: Event-specific data. For call events, this can include call status, provider, direction, context ID, channel UUID, failure reason, or duration when available. For WebRTC events, this can include session ID, media session ID, codec, ICE latency, peer connection state, reconnect reason, or recovery counters when available. For `conversation.completed`, this includes:
  * **reason**: Completion reason, usually `conversation_completed`.
  * **status**: Final conversation status.
  * **messages**: Transcript entries with message ID, role, and content.
  * **metadata**: Conversation metadata, including successful analysis results under `analysis.<analysis_name>`.
  * **metrics**: Conversation metrics recorded during the session.

### Response

<Frame>
  <img alt="Webhook Logs Response Tab" />
</Frame>

Shows the response details from the webhook endpoint:

* **body**: The response body (empty in this example)
* **headers**: Various HTTP headers in the response
  * **Alt-Svc**: Alternative services information
  * **Cf-Cache-Status**: Cloudflare cache status
  * **Cf-Ray**: Cloudflare Ray ID for the request
  * **Content-Length**: Length of the response content
  * **Content-Type**: MIME type of the response
  * **Date**: Timestamp of the response
  * **Nel**: Network Error Logging information
  * **Report-To**: Reporting API configuration

## Using Webhook Logs

1. **Integration Monitoring**: Track successful and failed webhook deliveries to ensure your integrations are working correctly.
2. **Debugging**: Investigate issues by examining the full request and response details for each webhook.
3. **Performance Analysis**: Monitor response times and success rates to optimize your webhook-based processes.
4. **Security Auditing**: Review webhook payloads and endpoints to ensure data is being sent to and received from authorized sources.

## Use Cases

<CardGroup>
  <Card title="Troubleshoot Integrations" icon="bug">
    Quickly identify and resolve issues with third-party integrations by
    examining detailed webhook logs.
  </Card>

  <Card title="Monitor Event Flow" icon="network">
    Track call, WebRTC, and conversation events and ensure they are being properly transmitted to
    external systems.
  </Card>

  <Card title="Optimize Performance" icon="brain">
    Analyze response times and success rates to improve the efficiency of your
    webhook-based processes.
  </Card>

  <Card title="Ensure Data Integrity" icon="shield-check">
    Verify that webhook payloads contain the expected data and are being sent to
    the correct endpoints.
  </Card>
</CardGroup>


# Create API Deployment
Source: https://doc.rapida.ai/api-reference/assistant/create-api-deployment

Create an assistant API deployment from the Rapida SDK.

Creates an API deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantDeploymentRequest">
  Provide the `api` deployment variant.

  <Expandable>
    <ParamField type="AssistantApiDeployment">
      API deployment configuration.

      <Expandable>
        <ParamField type="uint64">
          Assistant ID for the deployment.
        </ParamField>

        <ParamField type="string">
          First message the assistant sends when the session starts.
        </ParamField>

        <ParamField type="boolean">
          Controls whether users can interrupt the opening greeting in audio sessions.
        </ParamField>

        <ParamField type="string">
          Message to use when the assistant cannot understand or handle the input.
        </ParamField>

        <ParamField type="double">
          Seconds to wait after interrupted or unclear input before asking the user to repeat. Must be between `0.5` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the assistant could not understand the user input. Maximum length is `250` characters.
        </ParamField>

        <ParamField type="uint64">
          Idle timeout in seconds. Must be between `5` and `120`.
        </ParamField>

        <ParamField type="uint64">
          Number of idle-timeout retries. Must be between `0` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the session reaches the idle timeout.
        </ParamField>

        <ParamField type="uint64">
          Maximum session duration in seconds. Must be between `180` and `600`.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Speech-to-text audio provider configuration.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Text-to-speech audio provider configuration.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantApiDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantApiDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantApiDeployment();
  deployment.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);

  const request = new CreateAssistantDeploymentRequest();
  request.setApi(deployment);

  const response = await CreateAssistantApiDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantApiDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantApiDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantApiDeployment();
  deployment.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);

  const request = new CreateAssistantDeploymentRequest();
  request.setApi(deployment);

  const response = await CreateAssistantApiDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      AssistantApiDeployment,
      ConnectionConfig,
      DeploymentAudioProvider,
      Metadata,
  )
  from rapida.clients.protos.assistant_deployment_pb2 import (
      CreateAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  deployment = AssistantApiDeployment(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      greeting="Hi, how can I help you today?",
      greetingInterruptible=False,
      mistake="Sorry, I did not understand that.",
      unclearInputTimeout=0.5,
      unclearInputMessage="I didn't catch that. Could you repeat that?",
      idealTimeout=30,
      idealTimeoutBackoff=2,
      idealTimeoutMessage="Are you still there?",
      maxSessionDuration=300,
      inputAudio=DeploymentAudioProvider(
          audioProvider="deepgram",
          audioType="stt",
          audioOptions=[Metadata(key="model", value="nova-3")],
      ),
      outputAudio=DeploymentAudioProvider(
          audioProvider="elevenlabs",
          audioType="tts",
          audioOptions=[Metadata(key="voiceId", value="VOICE_ID_PLACEHOLDER")],
      ),
  )

  response = connection_config.assistant_deployment_client.CreateAssistantApiDeployment(
      CreateAssistantDeploymentRequest(api=deployment),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"google.golang.org/protobuf/proto"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.CreateAssistantApiDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantDeploymentRequest{
  			Deployment: &protos.CreateAssistantDeploymentRequest_Api{
  				Api: &protos.AssistantApiDeployment{
  					AssistantId:         2227823180112723968,
  					Greeting:            proto.String("Hi, how can I help you today?"),
  					GreetingInterruptible: proto.Bool(false),
  					Mistake:             proto.String("Sorry, I did not understand that."),
  					UnclearInputTimeout: proto.Float64(0.5),
  					UnclearInputMessage: proto.String("I didn't catch that. Could you repeat that?"),
  					IdealTimeout:        30,
  					IdealTimeoutBackoff: 2,
  					IdealTimeoutMessage: "Are you still there?",
  					MaxSessionDuration:  300,
  					InputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "deepgram",
  						AudioType:     "stt",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "model",
  							Value: "nova-3",
  						}},
  					},
  					OutputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "elevenlabs",
  						AudioType:     "tts",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "voiceId",
  							Value: "VOICE_ID_PLACEHOLDER",
  						}},
  					},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("create deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantApiDeployment">
  Created API deployment.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message for the session.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `1006001` | Invalid request.                                              |
| `1006002` | Unauthenticated request.                                      |
| `1006003` | Missing authentication scope.                                 |
| `1006004` | Invalid `assistantId`.                                        |
| `1006005` | Unable to create assistant API deployment.                    |
| `1006006` | Invalid `audioProvider`.                                      |
| `1006007` | `idealTimeout` must be between `5` and `120` seconds.         |
| `1006008` | `idealTimeoutBackoff` must be between `0` and `5` times.      |
| `1006009` | `maxSessionDuration` must be between `180` and `600` seconds. |


# Create Assistant
Source: https://doc.rapida.ai/api-reference/assistant/create-assistant

Create an assistant from the Rapida SDK.

Creates an assistant with one provider configuration. You can also attach tags, tools, and knowledge during creation.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantRequest">
  <Expandable>
    <ParamField type="string">
      Assistant name.
    </ParamField>

    <ParamField type="CreateAssistantProviderRequest">
      Provider configuration for the assistant. Provide exactly one of `model`, `agentkit`, or `websocket`.

      <Expandable>
        <ParamField type="string">
          Description for this provider configuration.
        </ParamField>

        <ParamField type="CreateAssistantProviderModel">
          Model-backed provider configuration.

          <Expandable>
            <ParamField type="string">
              Model provider name, such as `openai`.
            </ParamField>

            <ParamField type="TextChatCompletePrompt">
              Prompt template used by the model provider.
            </ParamField>

            <ParamField type="Metadata[]">
              Provider-specific model options.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="CreateAssistantProviderAgentkit">
          AgentKit provider configuration.

          <Expandable>
            <ParamField type="string">
              AgentKit gRPC endpoint in `host` or `host:port` format.
            </ParamField>

            <ParamField type="map<string, string>">
              gRPC metadata sent to your AgentKit server, such as auth or routing keys.
            </ParamField>

            <ParamField type="string">
              Transport mode. Use `TLS` or `PLAINTEXT`. Defaults to `TLS`.
            </ParamField>

            <ParamField type="string">
              TLS verification mode. Use `VERIFY` or `SKIP_VERIFY`. Defaults to `VERIFY`.
            </ParamField>

            <ParamField type="string">
              Server name used for TLS verification when it differs from the dial address.
            </ParamField>

            <ParamField type="string">
              Optional PEM CA certificate for private or self-signed TLS.
            </ParamField>

            <ParamField type="uint32">
              Connection timeout in milliseconds. Allowed range: `1` to `300000`.
            </ParamField>

            <ParamField type="uint32">
              Keepalive ping interval in milliseconds. Allowed range: `10000` to `3600000`.
            </ParamField>

            <ParamField type="uint32">
              Keepalive response timeout in milliseconds. Allowed range: `1000` to `300000`.
            </ParamField>

            <ParamField type="uint32">
              Maximum inbound gRPC message size. Allowed range: `1024` to `104857600`.
            </ParamField>

            <ParamField type="uint32">
              Maximum outbound gRPC message size. Allowed range: `1024` to `104857600`.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="CreateAssistantProviderWebsocket">
          WebSocket provider configuration.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Assistant description.
    </ParamField>

    <ParamField type="string">
      Assistant visibility, for example `private`.
    </ParamField>

    <ParamField type="string">
      Assistant language code, for example `en`.
    </ParamField>

    <ParamField type="string[]">
      Tags to attach to the assistant.
    </ParamField>

    <ParamField type="CreateAssistantToolRequest[]">
      Tools to attach to the assistant.
    </ParamField>

    <ParamField type="CreateAssistantKnowledgeRequest[]">
      Knowledge sources to attach to the assistant.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    CreateAssistant,
    CreateAssistantRequest,
    CreateAssistantProviderRequest,
    Metadata,
    TextChatCompletePrompt,
    TextPrompt,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithPersonalToken({
    Authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    AuthId: "AUTH_ID_PLACEHOLDER",
    ProjectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const systemPrompt = new TextPrompt();
  systemPrompt.setRole("system");
  systemPrompt.setContent("You are a helpful support assistant.");

  const template = new TextChatCompletePrompt();
  template.addPrompt(systemPrompt);

  const modelOption = new Metadata();
  modelOption.setKey("model");
  modelOption.setValue("gpt-4o-mini");

  const model = new CreateAssistantProviderRequest.CreateAssistantProviderModel();
  model.setModelprovidername("openai");
  model.setTemplate(template);
  model.addAssistantmodeloptions(modelOption);

  const provider = new CreateAssistantProviderRequest();
  provider.setDescription("Primary model provider");
  provider.setModel(model);

  const request = new CreateAssistantRequest();
  request.setName("Support assistant");
  request.setDescription("Answers customer support questions.");
  request.setVisibility("private");
  request.setLanguage("en");
  request.setTagsList(["support", "production"]);
  request.setAssistantprovider(provider);

  const response = await CreateAssistant(connectionCfg, request, auth);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    CreateAssistant,
    CreateAssistantRequest,
    CreateAssistantProviderRequest,
    Metadata,
    TextChatCompletePrompt,
    TextPrompt,
  } from "@rapidaai/nodejs";

  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({
      ApiKey: process.env.RAPIDA_API_KEY,
    })
  );

  const systemPrompt = new TextPrompt();
  systemPrompt.setRole("system");
  systemPrompt.setContent("You are a helpful support assistant.");

  const template = new TextChatCompletePrompt();
  template.addPrompt(systemPrompt);

  const modelOption = new Metadata();
  modelOption.setKey("model");
  modelOption.setValue("gpt-4o-mini");

  const model = new CreateAssistantProviderRequest.CreateAssistantProviderModel();
  model.setModelprovidername("openai");
  model.setTemplate(template);
  model.addAssistantmodeloptions(modelOption);

  const provider = new CreateAssistantProviderRequest();
  provider.setDescription("Primary model provider");
  provider.setModel(model);

  const request = new CreateAssistantRequest();
  request.setName("Support assistant");
  request.setDescription("Answers customer support questions.");
  request.setVisibility("private");
  request.setLanguage("en");
  request.setTagsList(["support", "production"]);
  request.setAssistantprovider(provider);

  try {
    const response = await CreateAssistant(connectionCfg, request);
    console.dir(response.toObject());
  } catch (error) {
    console.error("Error with CreateAssistant call:", error);
  }
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      ConnectionConfig,
      CreateAssistantProviderRequest,
      CreateAssistantRequest,
      Metadata,
      TextChatCompletePrompt,
      TextPrompt,
      create_assistant,
  )

  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(os.getenv("RAPIDA_API_KEY"))
  )

  provider = CreateAssistantProviderRequest(
      description="Primary model provider",
      model=CreateAssistantProviderRequest.CreateAssistantProviderModel(
          modelProviderName="openai",
          template=TextChatCompletePrompt(
              prompt=[
                  TextPrompt(
                      role="system",
                      content="You are a helpful support assistant.",
                  )
              ],
          ),
          assistantModelOptions=[
              Metadata(key="model", value="gpt-4o-mini"),
          ],
      ),
  )

  response = create_assistant(
      client_cfg=connection_config,
      request=CreateAssistantRequest(
          name="Support assistant",
          description="Answers customer support questions.",
          visibility="private",
          language="en",
          tags=["support", "production"],
          assistantProvider=provider,
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/rapidaai/rapida-go/rapida/clients"
  	"github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithSDK(os.Getenv("RAPIDA_API_KEY")),
  	)

  	response, err := clients.CreateAssistant(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantRequest{
  			Name:        "Support assistant",
  			Description: "Answers customer support questions.",
  			Visibility:  "private",
  			Language:    "en",
  			Tags:        []string{"support", "production"},
  			AssistantProvider: &protos.CreateAssistantProviderRequest{
  				Description: "Primary model provider",
  				AssistantProvider: &protos.CreateAssistantProviderRequest_Model{
  					Model: &protos.CreateAssistantProviderRequest_CreateAssistantProviderModel{
  						ModelProviderName: "openai",
  						Template: &protos.TextChatCompletePrompt{
  							Prompt: []*protos.TextPrompt{{
  								Role:    "system",
  								Content: "You are a helpful support assistant.",
  							}},
  						},
  						AssistantModelOptions: []*protos.Metadata{{
  							Key:   "model",
  							Value: "gpt-4o-mini",
  						}},
  					},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating assistant: %+v\n", err)
  		return
  	}
  	fmt.Printf("create assistant response: %+v\n", response)
  }
  ```
</CodeGroup>

## Create an AgentKit assistant

Use the `agentkit` provider when Rapida should handle telephony, STT, and TTS while your backend handles reasoning over the AgentKit gRPC stream.

<CodeGroup>
  ```json REST request theme={null}
  {
    "name": "AgentKit support assistant",
    "description": "Routes live conversations to a custom AgentKit backend.",
    "visibility": "private",
    "language": "en",
    "tags": ["support", "agentkit"],
    "assistantProvider": {
      "description": "AgentKit production backend",
      "agentkit": {
        "agentKitUrl": "agent.your-domain.com:50051",
        "metadata": {
          "authorization": "shared-token",
          "tenant": "acme"
        },
        "transportSecurity": "TLS",
        "tlsVerification": "VERIFY",
        "tlsServerName": "agent.your-domain.com",
        "connectTimeoutMs": 10000,
        "keepaliveTimeMs": 30000,
        "keepaliveTimeoutMs": 10000,
        "maxRecvMessageBytes": 16777216,
        "maxSendMessageBytes": 16777216
      }
    }
  }
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    CreateAssistant,
    CreateAssistantProviderRequest,
    CreateAssistantRequest,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithPersonalToken({
    Authorization: process.env.RAPIDA_AUTHORIZATION,
    AuthId: process.env.RAPIDA_AUTH_ID,
    ProjectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const agentkit = new CreateAssistantProviderRequest.CreateAssistantProviderAgentkit();
  agentkit.setAgentkiturl("agent.your-domain.com:50051");
  agentkit.setTransportsecurity("TLS");
  agentkit.setTlsverification("VERIFY");
  agentkit.setTlsservername("agent.your-domain.com");
  agentkit.setConnecttimeoutms(10000);
  agentkit.setKeepalivetimems(30000);
  agentkit.setKeepalivetimeoutms(10000);
  agentkit.setMaxrecvmessagebytes(16777216);
  agentkit.setMaxsendmessagebytes(16777216);
  agentkit.getMetadataMap().set("authorization", process.env.AGENTKIT_TOKEN || "");

  const provider = new CreateAssistantProviderRequest();
  provider.setDescription("AgentKit production backend");
  provider.setAgentkit(agentkit);

  const request = new CreateAssistantRequest();
  request.setName("AgentKit support assistant");
  request.setDescription("Routes live conversations to a custom AgentKit backend.");
  request.setVisibility("private");
  request.setLanguage("en");
  request.setTagsList(["support", "agentkit"]);
  request.setAssistantprovider(provider);

  const response = await CreateAssistant(connectionCfg, request, auth);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      ConnectionConfig,
      CreateAssistantProviderRequest,
      CreateAssistantRequest,
      create_assistant,
  )

  auth = ConnectionConfig.with_personal_token(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      auth_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  provider = CreateAssistantProviderRequest(
      description="AgentKit production backend",
      agentkit=CreateAssistantProviderRequest.CreateAssistantProviderAgentkit(
          agentKitUrl="agent.your-domain.com:50051",
          metadata={"authorization": os.getenv("AGENTKIT_TOKEN", "")},
          transportSecurity="TLS",
          tlsVerification="VERIFY",
          tlsServerName="agent.your-domain.com",
          connectTimeoutMs=10000,
          keepaliveTimeMs=30000,
          keepaliveTimeoutMs=10000,
          maxRecvMessageBytes=16777216,
          maxSendMessageBytes=16777216,
      ),
  )

  response = create_assistant(
      client_cfg=connection_config,
      request=CreateAssistantRequest(
          name="AgentKit support assistant",
          description="Routes live conversations to a custom AgentKit backend.",
          visibility="private",
          language="en",
          tags=["support", "agentkit"],
          assistantProvider=provider,
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/rapidaai/rapida-go/rapida/clients"
  	"github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	request := &protos.CreateAssistantRequest{
  		Name:        "AgentKit support assistant",
  		Description: "Routes live conversations to a custom AgentKit backend.",
  		Visibility:  "private",
  		Language:    "en",
  		Tags:        []string{"support", "agentkit"},
  		AssistantProvider: &protos.CreateAssistantProviderRequest{
  			Description: "AgentKit production backend",
  			AssistantProvider: &protos.CreateAssistantProviderRequest_Agentkit{
  				Agentkit: &protos.CreateAssistantProviderRequest_CreateAssistantProviderAgentkit{
  					AgentKitUrl:         "agent.your-domain.com:50051",
  					Metadata:            map[string]string{"authorization": os.Getenv("AGENTKIT_TOKEN")},
  					TransportSecurity:   "TLS",
  					TlsVerification:     "VERIFY",
  					TlsServerName:       "agent.your-domain.com",
  					ConnectTimeoutMs:    10000,
  					KeepaliveTimeMs:     30000,
  					KeepaliveTimeoutMs:  10000,
  					MaxRecvMessageBytes: 16777216,
  					MaxSendMessageBytes: 16777216,
  				},
  			},
  		},
  	}

  	response, err := clients.CreateAssistant(context.Background(), connectionConfig, request)
  	if err != nil {
  		fmt.Printf("error while creating AgentKit assistant: %+v\n", err)
  		return
  	}
  	fmt.Printf("create assistant response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Assistant">
  Created assistant.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant.
    </ParamField>

    <ParamField type="string">
      Assistant name.
    </ParamField>

    <ParamField type="string">
      Assistant description.
    </ParamField>

    <ParamField type="string">
      Current assistant status.
    </ParamField>

    <ParamField type="string">
      Assistant visibility.
    </ParamField>

    <ParamField type="string">
      Active provider type.
    </ParamField>

    <ParamField type="AssistantProviderModel">
      Model provider details when the assistant uses a model-backed provider.
    </ParamField>

    <ParamField type="AssistantProviderAgentkit">
      AgentKit provider details when the assistant uses AgentKit.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the AgentKit provider version.
        </ParamField>

        <ParamField type="string">
          AgentKit gRPC endpoint.
        </ParamField>

        <ParamField type="map<string, string>">
          Metadata sent to the AgentKit backend.
        </ParamField>

        <ParamField type="string">
          Transport mode for the AgentKit connection.
        </ParamField>

        <ParamField type="string">
          TLS verification mode.
        </ParamField>

        <ParamField type="string">
          TLS server name override.
        </ParamField>

        <ParamField type="uint32">
          Connection timeout in milliseconds.
        </ParamField>

        <ParamField type="uint32">
          Keepalive ping interval in milliseconds.
        </ParamField>

        <ParamField type="uint32">
          Keepalive response timeout in milliseconds.
        </ParamField>

        <ParamField type="uint32">
          Maximum inbound gRPC message size.
        </ParamField>

        <ParamField type="uint32">
          Maximum outbound gRPC message size.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="AssistantProviderWebsocket">
      WebSocket provider details when the assistant uses a WebSocket provider.
    </ParamField>

    <ParamField type="AssistantTool[]">
      Tools attached to the assistant.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.
</ParamField>


# Create Assistant Provider
Source: https://doc.rapida.ai/api-reference/assistant/create-assistant-provider

Create a provider configuration for an existing assistant.

Creates a new provider configuration for an existing assistant. Use this operation to create a new assistant version backed by a model, AgentKit, or WebSocket provider.

The new provider is created as a version candidate. Promote it with [Update assistant version](/api-reference/assistant/update-assistant-version) when you want the assistant to use it for live traffic.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantProviderRequest">
  Provider configuration for an existing assistant. Provide exactly one of `model`, `agentkit`, or `websocket`.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID that owns this provider version.
    </ParamField>

    <ParamField type="string">
      Version note or change description.
    </ParamField>

    <ParamField type="CreateAssistantProviderModel">
      Model-backed provider configuration.

      <Expandable>
        <ParamField type="string">
          Model provider name, such as `openai`, `anthropic`, or `azure-foundry`.
        </ParamField>

        <ParamField type="TextChatCompletePrompt">
          Prompt template used by the model provider.
        </ParamField>

        <ParamField type="Metadata[]">
          Provider-specific model options, such as `model.name`, `model.id`, and `model.temperature`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="CreateAssistantProviderAgentkit">
      AgentKit provider configuration.

      <Expandable>
        <ParamField type="string">
          AgentKit gRPC endpoint in `host` or `host:port` format.
        </ParamField>

        <ParamField type="map<string, string>">
          gRPC metadata sent to your AgentKit server.
        </ParamField>

        <ParamField type="string">
          Transport mode. Use `TLS` or `PLAINTEXT`. Defaults to `TLS`.
        </ParamField>

        <ParamField type="string">
          TLS verification mode. Use `VERIFY` or `SKIP_VERIFY`. Defaults to `VERIFY`.
        </ParamField>

        <ParamField type="string">
          Server name used for TLS verification when it differs from the dial address.
        </ParamField>

        <ParamField type="string">
          Optional PEM CA certificate for private or self-signed TLS.
        </ParamField>

        <ParamField type="uint32">
          Connection timeout in milliseconds. Allowed range: `1` to `300000`.
        </ParamField>

        <ParamField type="uint32">
          Keepalive ping interval in milliseconds. Allowed range: `10000` to `3600000`.
        </ParamField>

        <ParamField type="uint32">
          Keepalive response timeout in milliseconds. Allowed range: `1000` to `300000`.
        </ParamField>

        <ParamField type="uint32">
          Maximum inbound gRPC message size. Allowed range: `1024` to `104857600`.
        </ParamField>

        <ParamField type="uint32">
          Maximum outbound gRPC message size. Allowed range: `1024` to `104857600`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="CreateAssistantProviderWebsocket">
      WebSocket provider configuration.

      <Expandable>
        <ParamField type="string">
          WebSocket backend URL.
        </ParamField>

        <ParamField type="map<string, string>">
          Headers sent when Rapida connects to the WebSocket backend.
        </ParamField>

        <ParamField type="map<string, string>">
          Connection parameters sent to the WebSocket backend.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    CreateAssistantProvider,
    CreateAssistantProviderRequest,
    Metadata,
    TextChatCompletePrompt,
    TextPrompt,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const systemPrompt = new TextPrompt();
  systemPrompt.setRole("system");
  systemPrompt.setContent("You are a helpful support assistant.");

  const template = new TextChatCompletePrompt();
  template.addPrompt(systemPrompt);

  const modelName = new Metadata();
  modelName.setKey("model.name");
  modelName.setValue("gpt-4o-mini");

  const model = new CreateAssistantProviderRequest.CreateAssistantProviderModel();
  model.setModelprovidername("openai");
  model.setTemplate(template);
  model.setAssistantmodeloptionsList([modelName]);

  const request = new CreateAssistantProviderRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setDescription("Tune prompt and model parameters");
  request.setModel(model);

  const response = await CreateAssistantProvider(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    CreateAssistantProvider,
    CreateAssistantProviderRequest,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const agentkit = new CreateAssistantProviderRequest.CreateAssistantProviderAgentkit();
  agentkit.setAgentkiturl("agent.your-domain.com:50051");
  agentkit.setTransportsecurity("TLS");
  agentkit.setTlsverification("VERIFY");
  agentkit.setTlsservername("agent.your-domain.com");
  agentkit.setConnecttimeoutms(10000);
  agentkit.setKeepalivetimems(30000);
  agentkit.setKeepalivetimeoutms(10000);
  agentkit.setMaxrecvmessagebytes(16777216);
  agentkit.setMaxsendmessagebytes(16777216);
  agentkit.getMetadataMap().set("authorization", process.env.AGENTKIT_TOKEN || "");

  const request = new CreateAssistantProviderRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  request.setDescription("Move AgentKit to the production backend");
  request.setAgentkit(agentkit);

  try {
    const response = await CreateAssistantProvider(connectionCfg, request);
    console.dir(response.toObject());
  } catch (error) {
    console.error("Error with CreateAssistantProvider call:", error);
  }
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      ConnectionConfig,
      CreateAssistantProviderRequest,
      Metadata,
      TextChatCompletePrompt,
      TextPrompt,
      create_assistant_provider,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  provider = CreateAssistantProviderRequest(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      description="Tune prompt and model parameters",
      model=CreateAssistantProviderRequest.CreateAssistantProviderModel(
          modelProviderName="openai",
          template=TextChatCompletePrompt(
              prompt=[
                  TextPrompt(
                      role="system",
                      content="You are a helpful support assistant.",
                  )
              ],
          ),
          assistantModelOptions=[
              Metadata(key="model.name", value="gpt-4o-mini"),
          ],
      ),
  )

  response = create_assistant_provider(
      client_cfg=connection_config,
      request=provider,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/rapidaai/rapida-go/rapida/clients"
  	"github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	request := &protos.CreateAssistantProviderRequest{
  		AssistantId: 2227823180112723968,
  		Description: "Move AgentKit to the production backend",
  		AssistantProvider: &protos.CreateAssistantProviderRequest_Agentkit{
  			Agentkit: &protos.CreateAssistantProviderRequest_CreateAssistantProviderAgentkit{
  				AgentKitUrl:         "agent.your-domain.com:50051",
  				Metadata:            map[string]string{"authorization": os.Getenv("AGENTKIT_TOKEN")},
  				TransportSecurity:   "TLS",
  				TlsVerification:     "VERIFY",
  				TlsServerName:       "agent.your-domain.com",
  				ConnectTimeoutMs:    10000,
  				KeepaliveTimeMs:     30000,
  				KeepaliveTimeoutMs:  10000,
  				MaxRecvMessageBytes: 16777216,
  				MaxSendMessageBytes: 16777216,
  			},
  		},
  	}

  	response, err := clients.CreateAssistantProvider(context.Background(), connectionConfig, request)
  	if err != nil {
  		fmt.Printf("error while creating assistant provider: %+v\n", err)
  		return
  	}
  	fmt.Printf("create assistant provider response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantProviderModel">
  Returned when you create a model-backed provider version.
</ParamField>

<ParamField type="AssistantProviderAgentkit">
  Returned when you create an AgentKit provider version.
</ParamField>

<ParamField type="AssistantProviderWebsocket">
  Returned when you create a WebSocket provider version.
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.
</ParamField>


# Create Debugger Deployment
Source: https://doc.rapida.ai/api-reference/assistant/create-debugger-deployment

Create an assistant debugger deployment from the Rapida SDK.

Creates a debugger deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantDeploymentRequest">
  Provide the `debugger` deployment variant.

  <Expandable>
    <ParamField type="AssistantDebuggerDeployment">
      Debugger deployment configuration.

      <Expandable>
        <ParamField type="uint64">
          Assistant ID for the debugger deployment.
        </ParamField>

        <ParamField type="string">
          First message the assistant sends when the debugger session starts.
        </ParamField>

        <ParamField type="boolean">
          Controls whether users can interrupt the opening greeting in audio sessions.
        </ParamField>

        <ParamField type="string">
          Message to use when the assistant cannot understand or handle the input.
        </ParamField>

        <ParamField type="double">
          Seconds to wait after interrupted or unclear input before asking the user to repeat. Must be between `0.5` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the assistant could not understand the user input. Maximum length is `250` characters.
        </ParamField>

        <ParamField type="uint64">
          Idle timeout in seconds. Must be between `5` and `120`.
        </ParamField>

        <ParamField type="uint64">
          Number of idle-timeout retries. Must be between `0` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the debugger session reaches the idle timeout.
        </ParamField>

        <ParamField type="uint64">
          Maximum debugger session duration in seconds. Must be between `180` and `600`.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Speech-to-text audio provider configuration.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Text-to-speech audio provider configuration.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantDebuggerDeployment,
    ConnectionConfig,
    CreateAssistantDebuggerDeployment,
    CreateAssistantDeploymentRequest,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantDebuggerDeployment();
  deployment.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);

  const request = new CreateAssistantDeploymentRequest();
  request.setDebugger(deployment);

  const response = await CreateAssistantDebuggerDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantDebuggerDeployment,
    ConnectionConfig,
    CreateAssistantDebuggerDeployment,
    CreateAssistantDeploymentRequest,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantDebuggerDeployment();
  deployment.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);

  const request = new CreateAssistantDeploymentRequest();
  request.setDebugger(deployment);

  try {
    const response = await CreateAssistantDebuggerDeployment(connectionCfg, request);
    console.dir(response.toObject());
  } catch (error) {
    console.error("Error with CreateAssistantDebuggerDeployment call:", error);
  }
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      AssistantDebuggerDeployment,
      ConnectionConfig,
      DeploymentAudioProvider,
      Metadata,
  )
  from rapida.clients.protos.assistant_deployment_pb2 import (
      CreateAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  deployment = AssistantDebuggerDeployment(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      greeting="Hi, how can I help you today?",
      greetingInterruptible=False,
      mistake="Sorry, I did not understand that.",
      unclearInputTimeout=0.5,
      unclearInputMessage="I didn't catch that. Could you repeat that?",
      idealTimeout=30,
      idealTimeoutBackoff=2,
      idealTimeoutMessage="Are you still there?",
      maxSessionDuration=300,
      inputAudio=DeploymentAudioProvider(
          audioProvider="deepgram",
          audioType="stt",
          audioOptions=[Metadata(key="model", value="nova-3")],
      ),
      outputAudio=DeploymentAudioProvider(
          audioProvider="elevenlabs",
          audioType="tts",
          audioOptions=[Metadata(key="voiceId", value="VOICE_ID_PLACEHOLDER")],
      ),
  )

  response = connection_config.assistant_deployment_client.CreateAssistantDebuggerDeployment(
      CreateAssistantDeploymentRequest(debugger=deployment),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"google.golang.org/protobuf/proto"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.CreateAssistantDebuggerDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantDeploymentRequest{
  			Deployment: &protos.CreateAssistantDeploymentRequest_Debugger{
  				Debugger: &protos.AssistantDebuggerDeployment{
  					AssistantId:         2227823180112723968,
  					Greeting:            proto.String("Hi, how can I help you today?"),
  					GreetingInterruptible: proto.Bool(false),
  					Mistake:             proto.String("Sorry, I did not understand that."),
  					UnclearInputTimeout: proto.Float64(0.5),
  					UnclearInputMessage: proto.String("I didn't catch that. Could you repeat that?"),
  					IdealTimeout:        30,
  					IdealTimeoutBackoff: 2,
  					IdealTimeoutMessage: "Are you still there?",
  					MaxSessionDuration:  300,
  					InputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "deepgram",
  						AudioType:     "stt",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "model",
  							Value: "nova-3",
  						}},
  					},
  					OutputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "elevenlabs",
  						AudioType:     "tts",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "voiceId",
  							Value: "VOICE_ID_PLACEHOLDER",
  						}},
  					},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating debugger deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("create debugger deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantDebuggerDeployment">
  Created debugger deployment.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the debugger deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message for the debugger session.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum debugger session duration in seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `1004001` | Invalid request.                                              |
| `1004002` | Unauthenticated request.                                      |
| `1004003` | Missing authentication scope.                                 |
| `1004004` | Invalid `assistantId`.                                        |
| `1004005` | Unable to create assistant debugger deployment.               |
| `1004006` | Invalid `audioProvider`.                                      |
| `1004007` | `idealTimeout` must be between `5` and `120` seconds.         |
| `1004008` | `idealTimeoutBackoff` must be between `0` and `5` times.      |
| `1004009` | `maxSessionDuration` must be between `180` and `600` seconds. |


# Create Phone Deployment
Source: https://doc.rapida.ai/api-reference/assistant/create-phone-deployment

Create an assistant phone deployment from the Rapida SDK.

Creates a phone deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantDeploymentRequest">
  Provide the `phone` deployment variant.

  <Expandable>
    <ParamField type="AssistantPhoneDeployment">
      Phone deployment configuration.

      <Expandable>
        <ParamField type="uint64">
          Assistant ID for the deployment.
        </ParamField>

        <ParamField type="string">
          Telephony provider name, such as `twilio`, `vonage`, `exotel`, `asterisk`, or `sip`.
        </ParamField>

        <ParamField type="Metadata[]">
          Provider-specific phone options.
        </ParamField>

        <ParamField type="string">
          First message the assistant sends when the session starts.
        </ParamField>

        <ParamField type="boolean">
          Controls whether users can interrupt the opening greeting in audio sessions.
        </ParamField>

        <ParamField type="string">
          Message to use when the assistant cannot understand or handle the input.
        </ParamField>

        <ParamField type="double">
          Seconds to wait after interrupted or unclear input before asking the user to repeat. Must be between `0.5` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the assistant could not understand the user input. Maximum length is `250` characters.
        </ParamField>

        <ParamField type="uint64">
          Idle timeout in seconds. Must be between `5` and `120`.
        </ParamField>

        <ParamField type="uint64">
          Number of idle-timeout retries. Must be between `0` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the session reaches the idle timeout.
        </ParamField>

        <ParamField type="uint64">
          Maximum session duration in seconds. Must be between `180` and `600`.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Speech-to-text audio provider configuration.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Text-to-speech audio provider configuration.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantPhoneDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantPhoneDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantPhoneDeployment();
  deployment.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);
  const phoneNumber = new Metadata();
  phoneNumber.setKey("phoneNumber");
  phoneNumber.setValue("+14155550100");
  deployment.setPhoneprovidername("twilio");
  deployment.setPhoneoptionsList([phoneNumber]);

  const request = new CreateAssistantDeploymentRequest();
  request.setPhone(deployment);

  const response = await CreateAssistantPhoneDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantPhoneDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantPhoneDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantPhoneDeployment();
  deployment.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);
  const phoneNumber = new Metadata();
  phoneNumber.setKey("phoneNumber");
  phoneNumber.setValue("+14155550100");
  deployment.setPhoneprovidername("twilio");
  deployment.setPhoneoptionsList([phoneNumber]);

  const request = new CreateAssistantDeploymentRequest();
  request.setPhone(deployment);

  const response = await CreateAssistantPhoneDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      AssistantPhoneDeployment,
      ConnectionConfig,
      DeploymentAudioProvider,
      Metadata,
  )
  from rapida.clients.protos.assistant_deployment_pb2 import (
      CreateAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  deployment = AssistantPhoneDeployment(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      greeting="Hi, how can I help you today?",
      greetingInterruptible=False,
      mistake="Sorry, I did not understand that.",
      unclearInputTimeout=0.5,
      unclearInputMessage="I didn't catch that. Could you repeat that?",
      idealTimeout=30,
      idealTimeoutBackoff=2,
      idealTimeoutMessage="Are you still there?",
      maxSessionDuration=300,
      phoneProviderName="twilio",
      phoneOptions=[Metadata(key="phoneNumber", value="+14155550100")],
      inputAudio=DeploymentAudioProvider(
          audioProvider="deepgram",
          audioType="stt",
          audioOptions=[Metadata(key="model", value="nova-3")],
      ),
      outputAudio=DeploymentAudioProvider(
          audioProvider="elevenlabs",
          audioType="tts",
          audioOptions=[Metadata(key="voiceId", value="VOICE_ID_PLACEHOLDER")],
      ),
  )

  response = connection_config.assistant_deployment_client.CreateAssistantPhoneDeployment(
      CreateAssistantDeploymentRequest(phone=deployment),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"google.golang.org/protobuf/proto"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.CreateAssistantPhoneDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantDeploymentRequest{
  			Deployment: &protos.CreateAssistantDeploymentRequest_Phone{
  				Phone: &protos.AssistantPhoneDeployment{
  					AssistantId:         2227823180112723968,
  					Greeting:            proto.String("Hi, how can I help you today?"),
  					GreetingInterruptible: proto.Bool(false),
  					Mistake:             proto.String("Sorry, I did not understand that."),
  					UnclearInputTimeout: proto.Float64(0.5),
  					UnclearInputMessage: proto.String("I didn't catch that. Could you repeat that?"),
  					IdealTimeout:        30,
  					IdealTimeoutBackoff: 2,
  					IdealTimeoutMessage: "Are you still there?",
  					MaxSessionDuration:  300,
  					PhoneProviderName:   "twilio",
  					PhoneOptions: []*protos.Metadata{{
  						Key:   "phoneNumber",
  						Value: "+14155550100",
  					}},
  					InputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "deepgram",
  						AudioType:     "stt",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "model",
  							Value: "nova-3",
  						}},
  					},
  					OutputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "elevenlabs",
  						AudioType:     "tts",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "voiceId",
  							Value: "VOICE_ID_PLACEHOLDER",
  						}},
  					},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("create deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantPhoneDeployment">
  Created phone deployment.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      Telephony provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific phone options.
    </ParamField>

    <ParamField type="string">
      First message for the session.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `1005001` | Invalid request.                                              |
| `1005002` | Unauthenticated request.                                      |
| `1005003` | Missing authentication scope.                                 |
| `1005004` | Invalid `assistantId`.                                        |
| `1005005` | Unable to create assistant phone deployment.                  |
| `1005006` | Invalid `audioProvider`.                                      |
| `1005007` | `idealTimeout` must be between `5` and `120` seconds.         |
| `1005008` | `idealTimeoutBackoff` must be between `0` and `5` times.      |
| `1005009` | `maxSessionDuration` must be between `180` and `600` seconds. |
| `1005010` | Missing `phoneProviderName`.                                  |


# Create Web Plugin Deployment
Source: https://doc.rapida.ai/api-reference/assistant/create-webplugin-deployment

Create an assistant web plugin deployment from the Rapida SDK.

Creates a web plugin deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantDeploymentRequest">
  Provide the `plugin` deployment variant.

  <Expandable>
    <ParamField type="AssistantWebpluginDeployment">
      Web plugin deployment configuration.

      <Expandable>
        <ParamField type="uint64">
          Assistant ID for the deployment.
        </ParamField>

        <ParamField type="string[]">
          Suggested starter prompts shown in the web widget.
        </ParamField>

        <ParamField type="string">
          First message the assistant sends when the session starts.
        </ParamField>

        <ParamField type="boolean">
          Controls whether users can interrupt the opening greeting in audio sessions.
        </ParamField>

        <ParamField type="string">
          Message to use when the assistant cannot understand or handle the input.
        </ParamField>

        <ParamField type="double">
          Seconds to wait after interrupted or unclear input before asking the user to repeat. Must be between `0.5` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the assistant could not understand the user input. Maximum length is `250` characters.
        </ParamField>

        <ParamField type="uint64">
          Idle timeout in seconds. Must be between `5` and `120`.
        </ParamField>

        <ParamField type="uint64">
          Number of idle-timeout retries. Must be between `0` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the session reaches the idle timeout.
        </ParamField>

        <ParamField type="uint64">
          Maximum session duration in seconds. Must be between `180` and `600`.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Speech-to-text audio provider configuration.
        </ParamField>

        <ParamField type="DeploymentAudioProvider">
          Text-to-speech audio provider configuration.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantWebpluginDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantWebpluginDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantWebpluginDeployment();
  deployment.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);
  deployment.setSuggestionList(["Book a demo", "Talk to support"]);

  const request = new CreateAssistantDeploymentRequest();
  request.setPlugin(deployment);

  const response = await CreateAssistantWebpluginDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantWebpluginDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantWebpluginDeployment,
    DeploymentAudioProvider,
    Metadata,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const inputModel = new Metadata();
  inputModel.setKey("model");
  inputModel.setValue("nova-3");

  const inputAudio = new DeploymentAudioProvider();
  inputAudio.setAudioprovider("deepgram");
  inputAudio.setAudiotype("stt");
  inputAudio.setAudiooptionsList([inputModel]);

  const outputVoice = new Metadata();
  outputVoice.setKey("voiceId");
  outputVoice.setValue("VOICE_ID_PLACEHOLDER");

  const outputAudio = new DeploymentAudioProvider();
  outputAudio.setAudioprovider("elevenlabs");
  outputAudio.setAudiotype("tts");
  outputAudio.setAudiooptionsList([outputVoice]);

  const deployment = new AssistantWebpluginDeployment();
  deployment.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  deployment.setInputaudio(inputAudio);
  deployment.setOutputaudio(outputAudio);
  deployment.setSuggestionList(["Book a demo", "Talk to support"]);

  const request = new CreateAssistantDeploymentRequest();
  request.setPlugin(deployment);

  const response = await CreateAssistantWebpluginDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      AssistantWebpluginDeployment,
      ConnectionConfig,
      DeploymentAudioProvider,
      Metadata,
  )
  from rapida.clients.protos.assistant_deployment_pb2 import (
      CreateAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  deployment = AssistantWebpluginDeployment(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      greeting="Hi, how can I help you today?",
      greetingInterruptible=False,
      mistake="Sorry, I did not understand that.",
      unclearInputTimeout=0.5,
      unclearInputMessage="I didn't catch that. Could you repeat that?",
      idealTimeout=30,
      idealTimeoutBackoff=2,
      idealTimeoutMessage="Are you still there?",
      maxSessionDuration=300,
      suggestion=["Book a demo", "Talk to support"],
      inputAudio=DeploymentAudioProvider(
          audioProvider="deepgram",
          audioType="stt",
          audioOptions=[Metadata(key="model", value="nova-3")],
      ),
      outputAudio=DeploymentAudioProvider(
          audioProvider="elevenlabs",
          audioType="tts",
          audioOptions=[Metadata(key="voiceId", value="VOICE_ID_PLACEHOLDER")],
      ),
  )

  response = connection_config.assistant_deployment_client.CreateAssistantWebpluginDeployment(
      CreateAssistantDeploymentRequest(plugin=deployment),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"google.golang.org/protobuf/proto"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.CreateAssistantWebpluginDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantDeploymentRequest{
  			Deployment: &protos.CreateAssistantDeploymentRequest_Plugin{
  				Plugin: &protos.AssistantWebpluginDeployment{
  					AssistantId:         2227823180112723968,
  					Greeting:            proto.String("Hi, how can I help you today?"),
  					GreetingInterruptible: proto.Bool(false),
  					Mistake:             proto.String("Sorry, I did not understand that."),
  					UnclearInputTimeout: proto.Float64(0.5),
  					UnclearInputMessage: proto.String("I didn't catch that. Could you repeat that?"),
  					IdealTimeout:        30,
  					IdealTimeoutBackoff: 2,
  					IdealTimeoutMessage: "Are you still there?",
  					MaxSessionDuration:  300,
  					Suggestion:          []string{"Book a demo", "Talk to support"},
  					InputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "deepgram",
  						AudioType:     "stt",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "model",
  							Value: "nova-3",
  						}},
  					},
  					OutputAudio: &protos.DeploymentAudioProvider{
  						AudioProvider: "elevenlabs",
  						AudioType:     "tts",
  						AudioOptions: []*protos.Metadata{{
  							Key:   "voiceId",
  							Value: "VOICE_ID_PLACEHOLDER",
  						}},
  					},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("create deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWebpluginDeployment">
  Created web plugin deployment.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string[]">
      Suggested starter prompts configured for the web widget.
    </ParamField>

    <ParamField type="string">
      First message for the session.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `1007001` | Invalid request.                                              |
| `1007002` | Unauthenticated request.                                      |
| `1007003` | Missing authentication scope.                                 |
| `1007004` | Invalid `assistantId`.                                        |
| `1007005` | Unable to create assistant web plugin deployment.             |
| `1007006` | Invalid `audioProvider`.                                      |
| `1007007` | `idealTimeout` must be between `5` and `120` seconds.         |
| `1007008` | `idealTimeoutBackoff` must be between `0` and `5` times.      |
| `1007009` | `maxSessionDuration` must be between `180` and `600` seconds. |


# Create WhatsApp Deployment
Source: https://doc.rapida.ai/api-reference/assistant/create-whatsapp-deployment

Create an assistant WhatsApp deployment from the Rapida SDK.

Creates a WhatsApp deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateAssistantDeploymentRequest">
  Provide the `whatsapp` deployment variant.

  <Expandable>
    <ParamField type="AssistantWhatsappDeployment">
      WhatsApp deployment configuration.

      <Expandable>
        <ParamField type="uint64">
          Assistant ID for the deployment.
        </ParamField>

        <ParamField type="string">
          WhatsApp provider name.
        </ParamField>

        <ParamField type="Metadata[]">
          Provider-specific WhatsApp options.
        </ParamField>

        <ParamField type="string">
          First message the assistant sends when the session starts.
        </ParamField>

        <ParamField type="boolean">
          Controls whether users can interrupt the opening greeting in audio sessions.
        </ParamField>

        <ParamField type="string">
          Message to use when the assistant cannot understand or handle the input.
        </ParamField>

        <ParamField type="double">
          Seconds to wait after interrupted or unclear input before asking the user to repeat. Must be between `0.5` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the assistant could not understand the user input. Maximum length is `250` characters.
        </ParamField>

        <ParamField type="uint64">
          Idle timeout in seconds. Must be between `5` and `120`.
        </ParamField>

        <ParamField type="uint64">
          Number of idle-timeout retries. Must be between `0` and `5`.
        </ParamField>

        <ParamField type="string">
          Message sent when the session reaches the idle timeout.
        </ParamField>

        <ParamField type="uint64">
          Maximum session duration in seconds. Must be between `180` and `600`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantWhatsappDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantWhatsappDeployment,
    Metadata,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const deployment = new AssistantWhatsappDeployment();
  deployment.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  const template = new Metadata();
  template.setKey("template");
  template.setValue("welcome");
  deployment.setWhatsappprovidername("gupshup");
  deployment.setWhatsappoptionsList([template]);

  const request = new CreateAssistantDeploymentRequest();
  request.setWhatsapp(deployment);

  const response = await CreateAssistantWhatsappDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantWhatsappDeployment,
    ConnectionConfig,
    CreateAssistantDeploymentRequest,
    CreateAssistantWhatsappDeployment,
    Metadata,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const deployment = new AssistantWhatsappDeployment();
  deployment.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  deployment.setGreeting("Hi, how can I help you today?");
  deployment.setGreetinginterruptible(false);
  deployment.setMistake("Sorry, I did not understand that.");
  deployment.setUnclearinputtimeout(0.5);
  deployment.setUnclearinputmessage("I didn't catch that. Could you repeat that?");
  deployment.setIdealtimeout("30");
  deployment.setIdealtimeoutbackoff("2");
  deployment.setIdealtimeoutmessage("Are you still there?");
  deployment.setMaxsessionduration("300");
  const template = new Metadata();
  template.setKey("template");
  template.setValue("welcome");
  deployment.setWhatsappprovidername("gupshup");
  deployment.setWhatsappoptionsList([template]);

  const request = new CreateAssistantDeploymentRequest();
  request.setWhatsapp(deployment);

  const response = await CreateAssistantWhatsappDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      AssistantWhatsappDeployment,
      ConnectionConfig,
      Metadata,
  )
  from rapida.clients.protos.assistant_deployment_pb2 import (
      CreateAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  deployment = AssistantWhatsappDeployment(
      assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      greeting="Hi, how can I help you today?",
      greetingInterruptible=False,
      mistake="Sorry, I did not understand that.",
      unclearInputTimeout=0.5,
      unclearInputMessage="I didn't catch that. Could you repeat that?",
      idealTimeout=30,
      idealTimeoutBackoff=2,
      idealTimeoutMessage="Are you still there?",
      maxSessionDuration=300,
      whatsappProviderName="gupshup",
      whatsappOptions=[Metadata(key="template", value="welcome")],
  )

  response = connection_config.assistant_deployment_client.CreateAssistantWhatsappDeployment(
      CreateAssistantDeploymentRequest(whatsapp=deployment),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"google.golang.org/protobuf/proto"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.CreateAssistantWhatsappDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.CreateAssistantDeploymentRequest{
  			Deployment: &protos.CreateAssistantDeploymentRequest_Whatsapp{
  				Whatsapp: &protos.AssistantWhatsappDeployment{
  					AssistantId:         2227823180112723968,
  					Greeting:            proto.String("Hi, how can I help you today?"),
  					GreetingInterruptible: proto.Bool(false),
  					Mistake:             proto.String("Sorry, I did not understand that."),
  					UnclearInputTimeout: proto.Float64(0.5),
  					UnclearInputMessage: proto.String("I didn't catch that. Could you repeat that?"),
  					IdealTimeout:        30,
  					IdealTimeoutBackoff: 2,
  					IdealTimeoutMessage: "Are you still there?",
  					MaxSessionDuration:  300,
  					WhatsappProviderName: "gupshup",
  					WhatsappOptions: []*protos.Metadata{{
  						Key:   "template",
  						Value: "welcome",
  					}},
  				},
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("create deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWhatsappDeployment">
  Created WhatsApp deployment.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      WhatsApp provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific WhatsApp options.
    </ParamField>

    <ParamField type="string">
      First message for the session.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `1008001` | Invalid request.                                              |
| `1008002` | Unauthenticated request.                                      |
| `1008003` | Missing authentication scope.                                 |
| `1008004` | Invalid `assistantId`.                                        |
| `1008005` | Unable to create assistant WhatsApp deployment.               |
| `1008006` | `idealTimeout` must be between `5` and `120` seconds.         |
| `1008007` | `idealTimeoutBackoff` must be between `0` and `5` times.      |
| `1008008` | `maxSessionDuration` must be between `180` and `600` seconds. |
| `1008009` | Missing `whatsappProviderName`.                               |


# Get All API Deployments
Source: https://doc.rapida.ai/api-reference/assistant/get-all-api-deployment

Get assistant API deployments from the Rapida SDK.

Gets paginated API deployments for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantDeploymentRequest">
  Deployment list request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployments.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve.
        </ParamField>

        <ParamField type="uint32">
          Number of deployments to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional filtering criteria to apply to the deployment search.

      <Expandable>
        <ParamField type="string">
          Field name to filter by.
        </ParamField>

        <ParamField type="string">
          Value to match against the field.
        </ParamField>

        <ParamField type="string">
          Criteria logic. Accepted values: `should` or `must`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantDeploymentRequest,
    GetAllAssistantApiDeployment,
    Paginate,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const pagination = new Paginate();
  pagination.setPage(1);
  pagination.setPagesize(20);

  const request = new GetAllAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setPaginate(pagination);

  const response = await GetAllAssistantApiDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig, Paginate
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAllAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAllAssistantApiDeployment(
      GetAllAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          paginate=Paginate(page=1, pageSize=20),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAllAssistantApiDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAllAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  			Paginate: &protos.Paginate{
  				Page:     1,
  				PageSize: 20,
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting API deployments: %+v\n", err)
  		return
  	}
  	fmt.Printf("get API deployments response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantApiDeployment[]">
  API deployments returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the API deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.

  <Expandable>
    <ParamField type="uint32">
      Current page returned by the API.
    </ParamField>

    <ParamField type="uint32">
      Total number of matching deployments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                  |
| --------- | ---------------------------------------- |
| `1016001` | Unauthenticated request.                 |
| `1016002` | Missing authentication scope.            |
| `1016003` | Invalid `assistantId`.                   |
| `1016004` | Invalid request.                         |
| `1016005` | Unable to get assistant API deployments. |


# Get All Assistants
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant



Retrieves a paginated list of all assistants with optional filtering criteria using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantRequest">
  <Expandable>
    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          The page number to retrieve (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of assistants to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional array of filtering criteria to apply to the assistant search.

      <Expandable>
        <ParamField type="string">
          The field name to filter by.
        </ParamField>

        <ParamField type="string">
          The value to match against the specified key.
        </ParamField>

        <ParamField type="string">
          The logic operator for the criteria. Accepted values: "should" | "must"
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantRequest,
      get_all_assistant,
  )
  from pprint import pprint

  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant(
      client_cfg=connection_config,
      request=GetAllAssistantRequest(
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all assistants with pagination
  	response, err := clients.GetAllAssistant(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantRequest{
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "key",
  		// 	Value: "value",
  		// 	Logic: "should", // or "must"
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}

  import {
    ConnectionConfig,
    Paginate,
    GetAssistant,
    GetAllAssistant,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistant(connectionCfg);
  })();

  async function getAllAssistant(connectionCfg, page = 0, pageSize = 20) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantRequest();
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistant(connectionCfg, request);
      console.log("All Assistants Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistant call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Assistant[]">
  Array of assistant objects returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant.
    </ParamField>

    <ParamField type="string">
      Visibility setting of the assistant.
    </ParamField>

    <ParamField type="string">
      Source system or origin of the assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier mapping to the assistant's source.
    </ParamField>

    <ParamField type="AssistantTool[]">
      Array of tools available to the assistant.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the assistant provider.
    </ParamField>

    <ParamField type="AssistantProviderModel">
      Detailed information about the assistant's provider model.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the provider model.
        </ParamField>

        <ParamField type="TextChatCompletePrompt">
          Template configuration for text chat completion.

          <Expandable>
            <ParamField type="TextPrompt[]">
              Array of prompt configurations.

              <Expandable>
                <ParamField type="string">
                  Role of the prompt (e.g., "system", "user", "assistant").
                </ParamField>

                <ParamField type="string">
                  Content of the prompt.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="Variable[]">
              Array of variables used in the prompt template.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Description of the provider model.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the model provider.
        </ParamField>

        <ParamField type="string">
          Name of the model provider.
        </ParamField>

        <ParamField type="Metadata[]">
          Array of model configuration options.

          <Expandable>
            <ParamField type="uint64">
              Unique identifier for the metadata entry.
            </ParamField>

            <ParamField type="string">
              The option key name.
            </ParamField>

            <ParamField type="string">
              The option value.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Status of the provider model.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the creator.
        </ParamField>

        <ParamField type="User">
          User object of the creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="User">
          User object of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the provider model was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the provider model was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Name of the assistant.
    </ParamField>

    <ParamField type="string">
      Description of the assistant's purpose.
    </ParamField>

    <ParamField type="Tag">
      Tag information associated with the assistant.
    </ParamField>

    <ParamField type="string">
      Language setting for the assistant.
    </ParamField>

    <ParamField type="Organization">
      Organization details associated with the assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant creator.
    </ParamField>

    <ParamField type="User">
      User object of the assistant creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="User">
      User object of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant was last updated.
    </ParamField>

    <ParamField type="AssistantDebuggerDeployment">
      Configuration for debugger deployment.
    </ParamField>

    <ParamField type="AssistantPhoneDeployment">
      Configuration for phone deployment.
    </ParamField>

    <ParamField type="AssistantWhatsappDeployment">
      Configuration for WhatsApp deployment.
    </ParamField>

    <ParamField type="AssistantWebpluginDeployment">
      Configuration for web plugin deployment.
    </ParamField>

    <ParamField type="AssistantApiDeployment">
      Configuration for API deployment.
    </ParamField>

    <ParamField type="AssistantConversation[]">
      Array of conversations associated with the assistant.
    </ParamField>

    <ParamField type="AssistantWebhook[]">
      Array of webhooks configured for the assistant.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Pagination information for the response.

  <Expandable>
    <ParamField type="int64">
      Total number of assistants available.
    </ParamField>

    <ParamField type="int32">
      Total number of pages available.
    </ParamField>

    <ParamField type="int32">
      Current page number (0-based).
    </ParamField>

    <ParamField type="int32">
      Number of items per page.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are more pages available.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are previous pages available.
    </ParamField>
  </Expandable>
</ParamField>


# Get All Assistant Analysis
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-analysis



Retrieves a list of all assistant analyses with optional filtering and pagination using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantAnalysisRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant to retrieve analyses for.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve (0-based).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of search criteria to filter results.

      <Expandable>
        <ParamField type="string">
          The field key to filter on.
        </ParamField>

        <ParamField type="string">
          The value to filter by.
        </ParamField>

        <ParamField type="string">
          The logic operator for the filter. Accepted values: "should" or "must".
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantConversationRequest,
      get_all_assistant_conversation,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_conversation(
      client_cfg=connection_config,
      request=GetAllAssistantConversationRequest(
          assistantId="{assistant_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all assistant analyses with pagination
  	response, err := clients.GetAllAssistantAnalysis(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantAnalysisRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add search criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "key",
  		// 	Value: "value",
  		// 	Logic: "should", // or "must"
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}

  import {
    ConnectionConfig,
    Paginate,
    GetAllAssistantAnalysis,
    GetAllAssistantAnalysisRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistantAnalysis(connectionCfg, 56789678987890121, 0, 20);
  })();

  async function getAllAssistantAnalysis(connectionCfg, assistantId, page = 0, pageSize = 20) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantAnalysisRequest();
    request.setAssistantId(assistantId);
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistantAnalysis(request);
      console.log("All Assistant Analyses Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistantAnalysis call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantAnalysis[]">
  Array of assistant analysis objects.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant analysis.
    </ParamField>

    <ParamField type="string">
      Name of the assistant analysis.
    </ParamField>

    <ParamField type="string">
      Description of the assistant analysis purpose.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated endpoint.
    </ParamField>

    <ParamField type="string">
      Version of the endpoint being used.
    </ParamField>

    <ParamField type="map[string]string">
      Key-value pairs of parameters for the endpoint.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated assistant.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant analysis.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the analysis creator.
    </ParamField>

    <ParamField type="User">
      User object of the analysis creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="User">
      User object of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the analysis was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the analysis was last updated.
    </ParamField>

    <ParamField type="uint32">
      Priority level for analysis execution.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the response.
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get All Assistant Conversations
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-conversation



Retrieves a paginated list of conversations for a specific assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantConversationRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant whose conversations to retrieve.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the results.

      <Expandable>
        <ParamField type="uint32">
          Page number (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of filtering criteria to apply to the search.

      <Expandable>
        <ParamField type="string">
          The field key to filter on.
        </ParamField>

        <ParamField type="string">
          The value to match against.
        </ParamField>

        <ParamField type="string">
          Logic operator: "should" or "must".
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Source">
      Source filter for conversations.
    </ParamField>
  </Expandable>
</ParamField>

### Usages

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantConversationRequest,
      get_all_assistant_conversation,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_conversation(
      client_cfg=connection_config,
      request=GetAllAssistantConversationRequest(
          assistantId="{assistant_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go GO theme={null}
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all conversations for an assistant
  	response, err := clients.GetAllAssistantConversation(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantConversationRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Apply filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "status",
  		// 	Value: "active",
  		// 	Logic: "must",
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}

  import {
    ConnectionConfig,
    Paginate,
    GetAllAssistantConversation,
    GetAllAssistantConversationRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistantConversation(connectionCfg, 56789678987890121, 0, 20);
  })();

  async function getAllAssistantConversation(
    connectionCfg,
    assistantId,
    page = 0,
    pageSize = 20
  ) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantConversationRequest();
    request.setAssistantId(assistantId);
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistantConversation(
        connectionCfg,
        request
      );
      console.log("All Assistant Conversations Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistantConversation call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantConversation[]">
  Array of assistant conversations.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the conversation.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the user participating in the conversation.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant in the conversation.
    </ParamField>

    <ParamField type="string">
      Name or title of the conversation.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="string">
      Source platform or origin of the conversation.
    </ParamField>

    <ParamField type="string">
      External identifier for the conversation.
    </ParamField>

    <ParamField type="string">
      Current status of the conversation.
    </ParamField>

    <ParamField type="string">
      Direction of the conversation flow.
    </ParamField>

    <ParamField type="User">
      User information for the conversation participant.
    </ParamField>

    <ParamField type="uint64">
      Identifier for the assistant provider model used.
    </ParamField>

    <ParamField type="AssistantConversationMessage[]">
      Array of messages within the conversation.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the message.
        </ParamField>

        <ParamField type="string">
          External message identifier.
        </ParamField>

        <ParamField type="uint64">
          Parent conversation identifier.
        </ParamField>

        <ParamField type="uint64">
          Associated assistant identifier.
        </ParamField>

        <ParamField type="uint64">
          Model identifier used for this message.
        </ParamField>

        <ParamField type="Message">
          User's request message.
        </ParamField>

        <ParamField type="Message">
          Assistant's response message.
        </ParamField>

        <ParamField type="string">
          Source platform of the message.
        </ParamField>

        <ParamField type="string">
          Status of the message.
        </ParamField>

        <ParamField type="string[]">
          Array of suggested follow-up questions.
        </ParamField>

        <ParamField type="AssistantMessageStage[]">
          Processing stages for the message.
        </ParamField>

        <ParamField type="Metric[]">
          Performance metrics for the message.
        </ParamField>

        <ParamField type="Metadata[]">
          Additional metadata for the message.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the message creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the message was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the message was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="AssistantConversationContext[]">
      Array of conversation contexts.
    </ParamField>

    <ParamField type="Metric[]">
      Performance metrics for the conversation.
    </ParamField>

    <ParamField type="Metadata[]">
      Additional metadata for the conversation.
    </ParamField>

    <ParamField type="Argument[]">
      Arguments passed to the conversation.
    </ParamField>

    <ParamField type="Metadata[]">
      Configuration options for the conversation.
    </ParamField>

    <ParamField type="AssistantConversationRecording[]">
      Array of conversation recordings.

      <Expandable>
        <ParamField type="string">
          Pre-signed URL to access the assistant audio recording.
        </ParamField>

        <ParamField type="string">
          Pre-signed URL to access the user audio recording.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="uint64">
      Identifier of the conversation creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the conversation was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the conversation was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the response.

  <Expandable>
    <ParamField type="uint32">
      Current page number.
    </ParamField>

    <ParamField type="uint32">
      Number of items per page.
    </ParamField>

    <ParamField type="uint32">
      Total number of pages available.
    </ParamField>

    <ParamField type="uint64">
      Total number of items across all pages.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Technical error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get All Assistant Knowledge
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-knowledge



Retrieves a paginated list of all knowledge bases associated with a specific assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantKnowledgeRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant whose knowledge bases to retrieve.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the results.

      <Expandable>
        <ParamField type="uint32">
          The page number to retrieve (0-based).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of search criteria to filter the results.

      <Expandable>
        <ParamField type="string">
          The field name to filter by.
        </ParamField>

        <ParamField type="string">
          The value to filter for.
        </ParamField>

        <ParamField type="string">
          The logic operator for the criteria ("should" or "must").
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantKnowledgeRequest,
      get_all_assistant_knowledge,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_knowledge(
      client_cfg=connection_config,
      request=GetAllAssistantKnowledgeRequest(
          assistantId="{assistant_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all knowledge bases for an assistant
  	response, err := clients.GetAllAssistantKnowledge(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantKnowledgeRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add search criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "status",
  		// 	Value: "active",
  		// 	Logic: "must",
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}

  import {
    ConnectionConfig,
    Paginate,
    GetAllAssistantKnowledge,
    GetAllAssistantKnowledgeRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistantKnowledge(connectionCfg, 56789678987890121, 0, 20);
  })();


  async function getAllAssistantKnowledge(connectionCfg, assistantId, page = 0, pageSize = 20) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantKnowledgeRequest();
    request.setAssistantId(assistantId);
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistantKnowledge(connectionCfg, request);
      console.log("All Assistant Knowledge Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistantKnowledge call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantKnowledge[]">
  Array of assistant knowledge configurations.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant knowledge mapping.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated knowledge base.
    </ParamField>

    <ParamField type="boolean">
      Whether reranking is enabled for this knowledge base.
    </ParamField>

    <ParamField type="uint32">
      Number of top results to retrieve from the knowledge base.
    </ParamField>

    <ParamField type="float32">
      Minimum similarity score threshold for results.
    </ParamField>

    <ParamField type="Knowledge">
      Detailed information about the knowledge base.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the knowledge base.
        </ParamField>

        <ParamField type="string">
          Name of the knowledge base.
        </ParamField>

        <ParamField type="string">
          Description of the knowledge base purpose.
        </ParamField>

        <ParamField type="string">
          Visibility setting of the knowledge base.
        </ParamField>

        <ParamField type="string">
          Language setting for the knowledge base.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the embedding model provider.
        </ParamField>

        <ParamField type="string">
          Name of the embedding model provider.
        </ParamField>

        <ParamField type="Metadata[]">
          Array of embedding model configuration options.
        </ParamField>

        <ParamField type="string">
          Current status of the knowledge base.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the knowledge base creator.
        </ParamField>

        <ParamField type="User">
          User object of the knowledge base creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="User">
          User object of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the knowledge base was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the knowledge base was last updated.
        </ParamField>

        <ParamField type="uint64">
          Associated organization identifier.
        </ParamField>

        <ParamField type="uint64">
          Associated project identifier.
        </ParamField>

        <ParamField type="Organization">
          Organization details associated with the knowledge base.
        </ParamField>

        <ParamField type="Tag">
          Tag information associated with the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Number of documents in the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Total token count in the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Total word count in the knowledge base.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Method used for retrieving information from the knowledge base.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the reranker model provider.
    </ParamField>

    <ParamField type="string">
      Name of the reranker model provider.
    </ParamField>

    <ParamField type="Metadata[]">
      Array of reranker configuration options.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant knowledge mapping was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant knowledge mapping was last updated.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant knowledge mapping.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Technical error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the results.

  <Expandable>
    <ResponseField name="page" type="uint32">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="uint32">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalPages" type="uint32">
      Total number of pages available.
    </ResponseField>

    <ResponseField name="totalItems" type="uint64">
      Total number of items across all pages.
    </ResponseField>
  </Expandable>
</ParamField>


# Get All Assistant Tools
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-tool



Retrieves a paginated list of all assistant tools for a specific assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantToolRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant whose tools to retrieve.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the results.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve (0-indexed).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of search criteria for filtering results.

      <Expandable>
        <ParamField type="string">
          The field key to filter on.
        </ParamField>

        <ParamField type="string">
          The value to filter by.
        </ParamField>

        <ParamField type="string">
          Logic operator for the criteria ("should" | "must").
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantToolRequest,
      get_assistant_tool,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_tool(
      client_cfg=connection_config,
      request=GetAllAssistantToolRequest(
          assistantId="{assistant_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all assistant tools with pagination
  	response, err := clients.GetAllAssistantTool(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantToolRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "status",
  		// 	Value: "active",
  		// 	Logic: "must",
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }

  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantTool,
    GetAssistantToolRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantTool(connectionCfg, 45678903456789);
  })();


  async function getAssistantTool(connectionCfg, assistantId, toolId) {
    const request = new GetAssistantToolRequest();
    request.setAssistantId(assistantId);
    request.setId(toolId);

    try {
      const response = await GetAssistantTool(connectionCfg, request);
      console.log("Assistant Tool Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantTool call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantTool[]">
  Array of assistant tools.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant tool.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant that owns this tool.
    </ParamField>

    <ParamField type="string">
      Name of the assistant tool.
    </ParamField>

    <ParamField type="string">
      Description of the tool's functionality.
    </ParamField>

    <ParamField type="Struct">
      Tool fields configuration as a structured object.
    </ParamField>

    <ParamField type="string">
      Method used for tool execution.
    </ParamField>

    <ParamField type="Metadata[]">
      Array of execution configuration options.
    </ParamField>

    <ParamField type="string">
      Current status of the tool.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the tool was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the tool was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the results.
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get All Assistant Webhook
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-webhook



Retrieves a list of webhooks associated with a specific assistant using the Rapida API. This endpoint supports pagination and filtering capabilities.

<Info> For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication) </Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantWebhookRequest">
  <Expandable>
    <ParamField type="uint64">
      Filter results by a specific webhook ID.
    </ParamField>

    <ParamField type="uint64">
      Filter results by a specific assistant ID.
    </ParamField>

    <ParamField type="Paginate">
      Pagination settings for the results.

      <Expandable>
        <ParamField type="uint32">
          The page number (0-based).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of filtering criteria.

      <Expandable>
        <ParamField type="string">
          The field name to filter by.
        </ParamField>

        <ParamField type="string">
          The value to match against.
        </ParamField>

        <ParamField type="string">
          The logic operator to use ("should" or "must").
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantWebhookRequest,
      get_all_assistant_webhook,
  )
  from pprint import pprint

  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_webhook(
      client_cfg=connection_config,
      request=GetAllAssistantWebhookRequest(
          assistantId="{assistant_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all assistant webhooks with pagination
  	response, err := clients.GetAllAssistantWebhook(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantWebhookRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		//     Key:   "status",
  		//     Value: "active",
  		//     Logic: "must",
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantWebhook,
    GetAllAssistantWebhookRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistantWebhook(connectionCfg, 45678903456789);
  })();

  async function getAllAssistantWebhook(connectionCfg, assistantId, page = 0, pageSize = 20) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantWebhookRequest();
    request.setAssistantId(assistantId);
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistantWebhook(connectionCfg, request);
      console.log("All Assistant Webhooks Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistantWebhook call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWebhook[]">
  Array of assistant webhooks.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the webhook.
    </ParamField>

    <ParamField type="string[]">
      Array of call, WebRTC, or conversation event names that trigger this webhook.
    </ParamField>

    <ParamField type="string">
      Description of the webhook's purpose.
    </ParamField>

    <ParamField type="string">
      Webhook provider. HTTP webhooks use `http`.
    </ParamField>

    <ParamField type="Metadata[]">
      Delivery options for the webhook.

      <Expandable>
        <ResponseField name="http_method" type="string">
          HTTP method used for delivery. Supported values are `POST`, `PUT`, and `PATCH`.
        </ResponseField>

        <ResponseField name="http_url" type="string">
          Target URL where webhook requests are sent.
        </ResponseField>

        <ResponseField name="http_headers" type="string">
          JSON object containing HTTP headers included with each request.
        </ResponseField>

        <ResponseField name="retry_status_codes" type="string">
          JSON array of response status entries used by the delivery retry policy.
        </ResponseField>

        <ResponseField name="max_retry_count" type="string">
          Maximum number of retry attempts after a retryable failure.
        </ResponseField>

        <ResponseField name="timeout_seconds" type="string">
          Maximum time in seconds to wait for the webhook endpoint to respond.
        </ResponseField>
      </Expandable>
    </ParamField>

    <ParamField type="uint32">
      Execution priority of the webhook.
    </ParamField>

    <ParamField type="uint64">
      Associated assistant identifier.
    </ParamField>

    <ParamField type="string">
      Current status of the webhook.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the webhook creator.
    </ParamField>

    <ParamField type="User">
      User object of the webhook creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="User">
      User object of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the webhook was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the webhook was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Technical error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error description.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the results.
</ParamField>


# Get All Assistant HTTP Logs
Source: https://doc.rapida.ai/api-reference/assistant/get-all-assistant-webhook-log



Retrieves a paginated list of assistant HTTP logs, including webhook delivery logs, with optional filtering and ordering using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantHTTPLogRequest">
  <Expandable>
    <ParamField type="uint64">
      The project identifier for scope filtering.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration.

      <Expandable>
        <ParamField type="uint32">
          Page number (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of filtering criteria.

      <Expandable>
        <ParamField type="string">
          Field name to filter on.
        </ParamField>

        <ParamField type="string">
          Value to filter by.
        </ParamField>

        <ParamField type="string">
          Filter logic: "should" or "must".
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Ordering">
      Sorting configuration.

      <Expandable>
        <ParamField type="string">
          Column name to sort by.
        </ParamField>

        <ParamField type="string">
          Sort order: "asc" or "desc".
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllAssistantHTTPLogRequest,
      Paginate,
      get_all_assistant_http_log,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_all_assistant_http_log(
      client_cfg=connection_config,
      request=GetAllAssistantHTTPLogRequest(
          projectId="{project_id}",
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve paginated HTTP logs
  	response, err := clients.GetAllAssistantHTTPLog(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantHTTPLogRequest{
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "status",
  		// 	Value: "success",
  		// 	Logic: "must",
  		// }},
  		// Optional: Add sorting
  		// Order: &rapida_proto.Ordering{
  		// 	Column: "createdDate",
  		// 	Order:  "desc",
  		// },
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantHTTPLog,
    GetAllAssistantHTTPLogRequest,
    Paginate,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllAssistantHTTPLog(connectionCfg);
  })();


  async function getAllAssistantHTTPLog(connectionCfg, page = 0, pageSize = 20) {
    const pagination = new Paginate();
    pagination.setPage(page);
    pagination.setPageSize(pageSize);

    const request = new GetAllAssistantHTTPLogRequest();
    request.setPaginate(pagination);

    try {
      const response = await GetAllAssistantHTTPLog(connectionCfg, request);
      console.log("All Assistant HTTP Logs Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAllAssistantHTTPLog call:", error);
    }
  }


  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantHTTPLog[]">
  Array of assistant HTTP log entries.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the HTTP log.
    </ParamField>

    <ParamField type="uint64">
      Source record identifier. For webhook deliveries, this is the webhook ID.
    </ParamField>

    <ParamField type="object">
      The request payload sent to the webhook.
    </ParamField>

    <ParamField type="object">
      The response received from the webhook.
    </ParamField>

    <ParamField type="string">
      Status of the webhook execution.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was last updated.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated project.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated organization.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated conversation.
    </ParamField>

    <ParamField type="string">
      Asset prefix used for the webhook.
    </ParamField>

    <ParamField type="string">
      Event type that triggered the HTTP request, such as a call, WebRTC, or conversation webhook event.
    </ParamField>

    <ParamField type="uint64">
      HTTP response status code from the webhook.
    </ParamField>

    <ParamField type="uint64">
      Time taken for the webhook execution in milliseconds.
    </ParamField>

    <ParamField type="uint32">
      Number of retry attempts made.
    </ParamField>

    <ParamField type="string">
      HTTP method used for the webhook request.
    </ParamField>

    <ParamField type="string">
      URL that was called for the webhook.
    </ParamField>

    <ParamField type="string">
      Source category for the HTTP log.
    </ParamField>

    <ParamField type="string">
      Context identifier associated with the source event, when available.
    </ParamField>

    <ParamField type="string">
      Delivery error message, when the HTTP request fails.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get All Debugger Deployments
Source: https://doc.rapida.ai/api-reference/assistant/get-all-debugger-deployment

Get assistant debugger deployments from the Rapida SDK.

Gets paginated debugger deployments for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantDeploymentRequest">
  Deployment list request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployments.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve.
        </ParamField>

        <ParamField type="uint32">
          Number of deployments to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional filtering criteria to apply to the deployment search.

      <Expandable>
        <ParamField type="string">
          Field name to filter by.
        </ParamField>

        <ParamField type="string">
          Value to match against the field.
        </ParamField>

        <ParamField type="string">
          Criteria logic. Accepted values: `should` or `must`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantDeploymentRequest,
    GetAllAssistantDebuggerDeployment,
    Paginate,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const pagination = new Paginate();
  pagination.setPage(1);
  pagination.setPagesize(20);

  const request = new GetAllAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setPaginate(pagination);

  const response = await GetAllAssistantDebuggerDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig, Paginate
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAllAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAllAssistantDebuggerDeployment(
      GetAllAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          paginate=Paginate(page=1, pageSize=20),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAllAssistantDebuggerDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAllAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  			Paginate: &protos.Paginate{
  				Page:     1,
  				PageSize: 20,
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting debugger deployments: %+v\n", err)
  		return
  	}
  	fmt.Printf("get debugger deployments response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantDebuggerDeployment[]">
  Debugger deployments returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the debugger deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.

  <Expandable>
    <ParamField type="uint32">
      Current page returned by the API.
    </ParamField>

    <ParamField type="uint32">
      Total number of matching deployments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                       |
| --------- | --------------------------------------------- |
| `1014001` | Unauthenticated request.                      |
| `1014002` | Missing authentication scope.                 |
| `1014003` | Invalid `assistantId`.                        |
| `1014004` | Invalid request.                              |
| `1014005` | Unable to get assistant debugger deployments. |


# Get All Phone Deployments
Source: https://doc.rapida.ai/api-reference/assistant/get-all-phone-deployment

Get assistant phone deployments from the Rapida SDK.

Gets paginated phone deployments for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantDeploymentRequest">
  Deployment list request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployments.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve.
        </ParamField>

        <ParamField type="uint32">
          Number of deployments to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional filtering criteria to apply to the deployment search.

      <Expandable>
        <ParamField type="string">
          Field name to filter by.
        </ParamField>

        <ParamField type="string">
          Value to match against the field.
        </ParamField>

        <ParamField type="string">
          Criteria logic. Accepted values: `should` or `must`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantDeploymentRequest,
    GetAllAssistantPhoneDeployment,
    Paginate,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const pagination = new Paginate();
  pagination.setPage(1);
  pagination.setPagesize(20);

  const request = new GetAllAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setPaginate(pagination);

  const response = await GetAllAssistantPhoneDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig, Paginate
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAllAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAllAssistantPhoneDeployment(
      GetAllAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          paginate=Paginate(page=1, pageSize=20),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAllAssistantPhoneDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAllAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  			Paginate: &protos.Paginate{
  				Page:     1,
  				PageSize: 20,
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting phone deployments: %+v\n", err)
  		return
  	}
  	fmt.Printf("get phone deployments response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantPhoneDeployment[]">
  Phone deployments returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the phone deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific options.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.

  <Expandable>
    <ParamField type="uint32">
      Current page returned by the API.
    </ParamField>

    <ParamField type="uint32">
      Total number of matching deployments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                    |
| --------- | ------------------------------------------ |
| `1015001` | Unauthenticated request.                   |
| `1015002` | Missing authentication scope.              |
| `1015003` | Invalid `assistantId`.                     |
| `1015004` | Invalid request.                           |
| `1015005` | Unable to get assistant phone deployments. |


# Get All Webplugin Deployments
Source: https://doc.rapida.ai/api-reference/assistant/get-all-webplugin-deployment

Get assistant web plugin deployments from the Rapida SDK.

Gets paginated web plugin deployments for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantDeploymentRequest">
  Deployment list request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployments.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve.
        </ParamField>

        <ParamField type="uint32">
          Number of deployments to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional filtering criteria to apply to the deployment search.

      <Expandable>
        <ParamField type="string">
          Field name to filter by.
        </ParamField>

        <ParamField type="string">
          Value to match against the field.
        </ParamField>

        <ParamField type="string">
          Criteria logic. Accepted values: `should` or `must`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantDeploymentRequest,
    GetAllAssistantWebpluginDeployment,
    Paginate,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const pagination = new Paginate();
  pagination.setPage(1);
  pagination.setPagesize(20);

  const request = new GetAllAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setPaginate(pagination);

  const response = await GetAllAssistantWebpluginDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig, Paginate
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAllAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAllAssistantWebpluginDeployment(
      GetAllAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          paginate=Paginate(page=1, pageSize=20),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAllAssistantWebpluginDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAllAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  			Paginate: &protos.Paginate{
  				Page:     1,
  				PageSize: 20,
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting web plugin deployments: %+v\n", err)
  		return
  	}
  	fmt.Printf("get web plugin deployments response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWebpluginDeployment[]">
  Webplugin deployments returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the web plugin deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string[]">
      Suggested starter prompts.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.

  <Expandable>
    <ParamField type="uint32">
      Current page returned by the API.
    </ParamField>

    <ParamField type="uint32">
      Total number of matching deployments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                         |
| --------- | ----------------------------------------------- |
| `1017001` | Unauthenticated request.                        |
| `1017002` | Missing authentication scope.                   |
| `1017003` | Invalid `assistantId`.                          |
| `1017004` | Invalid request.                                |
| `1017005` | Unable to get assistant web plugin deployments. |


# Get All WhatsApp Deployments
Source: https://doc.rapida.ai/api-reference/assistant/get-all-whatsapp-deployment

Get assistant WhatsApp deployments from the Rapida SDK.

Gets paginated WhatsApp deployments for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantDeploymentRequest">
  Deployment list request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployments.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          Page number to retrieve.
        </ParamField>

        <ParamField type="uint32">
          Number of deployments to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional filtering criteria to apply to the deployment search.

      <Expandable>
        <ParamField type="string">
          Field name to filter by.
        </ParamField>

        <ParamField type="string">
          Value to match against the field.
        </ParamField>

        <ParamField type="string">
          Criteria logic. Accepted values: `should` or `must`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAllAssistantDeploymentRequest,
    GetAllAssistantWhatsappDeployment,
    Paginate,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const pagination = new Paginate();
  pagination.setPage(1);
  pagination.setPagesize(20);

  const request = new GetAllAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setPaginate(pagination);

  const response = await GetAllAssistantWhatsappDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig, Paginate
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAllAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAllAssistantWhatsappDeployment(
      GetAllAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          paginate=Paginate(page=1, pageSize=20),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAllAssistantWhatsappDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAllAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  			Paginate: &protos.Paginate{
  				Page:     1,
  				PageSize: 20,
  			},
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting WhatsApp deployments: %+v\n", err)
  		return
  	}
  	fmt.Printf("get WhatsApp deployments response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWhatsappDeployment[]">
  WhatsApp deployments returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the WhatsApp deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific options.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination metadata.

  <Expandable>
    <ParamField type="uint32">
      Current page returned by the API.
    </ParamField>

    <ParamField type="uint32">
      Total number of matching deployments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                       |
| --------- | --------------------------------------------- |
| `1018001` | Unauthenticated request.                      |
| `1018002` | Missing authentication scope.                 |
| `1018003` | Invalid `assistantId`.                        |
| `1018004` | Invalid request.                              |
| `1018005` | Unable to get assistant WhatsApp deployments. |


# Get API Deployment
Source: https://doc.rapida.ai/api-reference/assistant/get-api-deployment

Get an assistant API deployment from the Rapida SDK.

Gets the latest API deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantDeploymentRequest">
  Deployment lookup request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantApiDeployment,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");

  const response = await GetAssistantApiDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantApiDeployment,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);

  const response = await GetAssistantApiDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAssistantApiDeployment(
      GetAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAssistantApiDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting API deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("get API deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantApiDeployment">
  API deployment. If no deployment exists, the deployment field may be omitted.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the API deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                 |
| --------- | --------------------------------------- |
| `1011001` | Unauthenticated request.                |
| `1011002` | Missing authentication scope.           |
| `1011003` | Invalid `assistantId`.                  |
| `1011004` | Unable to get assistant API deployment. |


# Get Assistant
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant



Retrieves detailed information about a specific assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant to retrieve.
    </ParamField>

    <ParamField type="uint64">
      Optional identifier for the assistant provider model. Use utils.Ptr() to set this value.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantRequest,
      get_assistant,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(
          "{rapida-api-key}"
      )
  )
  response = get_assistant(
      client_cfg=connection_config,
      request=GetAssistantRequest(id=2227823180112723968),
  )
  pprint(response)

  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	"github.com/rapidaai/rapida-go/rapida/utils"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve assistant information
  	response, err := clients.GetAssistant(context.Background(), connectionConfig, &rapida_proto.GetAssistantRequest{
  		Id: 45678903456789,
  		// Optional: Specify assistant provider model ID
  		AssistantProviderModelId: utils.Ptr(uint64(3476544567890987654)),
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistant,
    GetAssistantRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistant(connectionCfg, "45678903456789", "3476544567890987654");
  })();

  async function getAssistant(connectionCfg, assistantId, providerModelId) {
    const request = new GetAssistantRequest();
    request.setId(assistantId);
    if (providerModelId) {
      request.setAssistantProviderModelId(providerModelId);
    }
    try {
      const response = await GetAssistant(connectionCfg, request);
      console.log("Assistant Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistant call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Assistant">
  Detailed information about the assistant.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant.
    </ParamField>

    <ParamField type="string">
      Visibility setting of the assistant.
    </ParamField>

    <ParamField type="string">
      Source system or origin of the assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier mapping to the assistant's source.
    </ParamField>

    <ParamField type="AssistantTool[]">
      Array of tools available to the assistant.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the assistant provider.
    </ParamField>

    <ParamField type="AssistantProviderModel">
      Detailed information about the assistant's provider model.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the provider model.
        </ParamField>

        <ParamField type="TextChatCompletePrompt">
          Template configuration for text chat completion.

          <Expandable>
            <ParamField type="TextPrompt[]">
              Array of prompt configurations.

              <Expandable>
                <ParamField type="string">
                  Role of the prompt (e.g., "system", "user", "assistant").
                </ParamField>

                <ParamField type="string">
                  Content of the prompt.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="Variable[]">
              Array of variables used in the prompt template.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Description of the provider model.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the model provider.
        </ParamField>

        <ParamField type="string">
          Name of the model provider.
        </ParamField>

        <ParamField type="Metadata[]">
          Array of model configuration options.

          <Expandable>
            <ParamField type="uint64">
              Unique identifier for the metadata entry.
            </ParamField>

            <ParamField type="string">
              The option key name.
            </ParamField>

            <ParamField type="string">
              The option value.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Status of the provider model.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the creator.
        </ParamField>

        <ParamField type="User">
          User object of the creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="User">
          User object of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the provider model was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the provider model was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Name of the assistant.
    </ParamField>

    <ParamField type="string">
      Description of the assistant's purpose.
    </ParamField>

    <ParamField type="Tag">
      Tag information associated with the assistant.
    </ParamField>

    <ParamField type="string">
      Language setting for the assistant.
    </ParamField>

    <ParamField type="Organization">
      Organization details associated with the assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant creator.
    </ParamField>

    <ParamField type="User">
      User object of the assistant creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="User">
      User object of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant was last updated.
    </ParamField>

    <ParamField type="AssistantDebuggerDeployment">
      Configuration for debugger deployment.
    </ParamField>

    <ParamField type="AssistantPhoneDeployment">
      Configuration for phone deployment.
    </ParamField>

    <ParamField type="AssistantWhatsappDeployment">
      Configuration for WhatsApp deployment.
    </ParamField>

    <ParamField type="AssistantWebpluginDeployment">
      Configuration for web plugin deployment.
    </ParamField>

    <ParamField type="AssistantApiDeployment">
      Configuration for API deployment.
    </ParamField>

    <ParamField type="AssistantConversation[]">
      Array of conversations associated with the assistant.
    </ParamField>

    <ParamField type="AssistantWebhook[]">
      Array of webhooks configured for the assistant.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant Analysis
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-analysis



Retrieves detailed information about a specific assistant analysis using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantAnalysisRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant analysis to retrieve.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the assistant associated with the analysis.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantAnalysisRequest,
      get_assistant_analysis,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_assistant_analysis(
      client_cfg=connection_config,
      request=GetAssistantAnalysisRequest(
          id="{assistant_analysis_id}", assistantId="{assistant_id}"
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve assistant analysis information
  	response, err := clients.GetAssistantAnalysis(context.Background(), connectionConfig, &rapida_proto.GetAssistantAnalysisRequest{
  		AssistantId: 3456789876541212,
  		Id:          567898765456788765,
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantAnalysis,
    GetAssistantAnalysisRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantAnalysis(connectionCfg, 3456789876541212, 567898765456788765);
  })();

  async function getAssistantAnalysis(connectionCfg, assistantId, analysisId) {
    const request = new GetAssistantAnalysisRequest();
    request.setAssistantId(assistantId);
    request.setId(analysisId);

    try {
      const response = await GetAssistantAnalysis(request);
      console.log("Assistant Analysis Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantAnalysis call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantAnalysis">
  Detailed information about the assistant analysis.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant analysis.
    </ParamField>

    <ParamField type="string">
      Name of the assistant analysis.
    </ParamField>

    <ParamField type="string">
      Description of the assistant analysis purpose.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated endpoint.
    </ParamField>

    <ParamField type="string">
      Version of the endpoint being used.
    </ParamField>

    <ParamField type="map[string]string">
      Key-value pairs of parameters for the endpoint.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated assistant.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant analysis.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the analysis creator.
    </ParamField>

    <ParamField type="User">
      User object of the analysis creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="User">
      User object of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the analysis was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the analysis was last updated.
    </ParamField>

    <ParamField type="uint32">
      Priority level for analysis execution.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant Conversation
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-conversation



Retrieves a paginated list of conversations for a specific assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllAssistantConversationRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant whose conversations to retrieve.
    </ParamField>

    <ParamField type="Paginate">
      Pagination configuration for the results.

      <Expandable>
        <ParamField type="uint32">
          Page number (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of items per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Array of filtering criteria to apply to the search.

      <Expandable>
        <ParamField type="string">
          The field key to filter on.
        </ParamField>

        <ParamField type="string">
          The value to match against.
        </ParamField>

        <ParamField type="string">
          Logic operator: "should" or "must".
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Source">
      Source filter for conversations.
    </ParamField>
  </Expandable>
</ParamField>

### Usages

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantConversationRequest,
      get_assistant_conversation,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_assistant_conversation(
      client_cfg=connection_config,
      request=GetAssistantConversationRequest(
          id="{assistant_conversation_id}", assistantId="{assistant_id}"
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve all conversations for an assistant
  	response, err := clients.GetAllAssistantConversation(context.Background(), connectionConfig, &rapida_proto.GetAllAssistantConversationRequest{
  		AssistantId: 3456789876541212,
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Apply filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "status",
  		// 	Value: "active",
  		// 	Logic: "must",
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantConversation,
    GetAssistantConversationRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantConversation(connectionCfg, "3456789876541212", "567898765456788765", [
      { field: "metadata" },
    ]);
  })();

  async function getAssistantConversation(connectionCfg, assistantId, conversationId, fields) {
    const request = new GetAssistantConversationRequest();
    request.setAssistantId(assistantId);
    request.setAssistantConversationId(conversationId);
    request.setSelectors(fields);

    try {
      const response =
        await GetAssistantConversation(connectionCfg, request);
      console.log("Assistant Conversation Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantConversation call:", error);
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantConversation[]">
  Array of assistant conversations.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the conversation.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the user participating in the conversation.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant in the conversation.
    </ParamField>

    <ParamField type="string">
      Name or title of the conversation.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="string">
      Source platform or origin of the conversation.
    </ParamField>

    <ParamField type="string">
      External identifier for the conversation.
    </ParamField>

    <ParamField type="string">
      Current status of the conversation.
    </ParamField>

    <ParamField type="string">
      Direction of the conversation flow.
    </ParamField>

    <ParamField type="User">
      User information for the conversation participant.
    </ParamField>

    <ParamField type="uint64">
      Identifier for the assistant provider model used.
    </ParamField>

    <ParamField type="AssistantConversationMessage[]">
      Array of messages within the conversation.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the message.
        </ParamField>

        <ParamField type="string">
          External message identifier.
        </ParamField>

        <ParamField type="uint64">
          Parent conversation identifier.
        </ParamField>

        <ParamField type="uint64">
          Associated assistant identifier.
        </ParamField>

        <ParamField type="uint64">
          Model identifier used for this message.
        </ParamField>

        <ParamField type="Message">
          User's request message.
        </ParamField>

        <ParamField type="Message">
          Assistant's response message.
        </ParamField>

        <ParamField type="string">
          Source platform of the message.
        </ParamField>

        <ParamField type="string">
          Status of the message.
        </ParamField>

        <ParamField type="string[]">
          Array of suggested follow-up questions.
        </ParamField>

        <ParamField type="AssistantMessageStage[]">
          Processing stages for the message.
        </ParamField>

        <ParamField type="Metric[]">
          Performance metrics for the message.
        </ParamField>

        <ParamField type="Metadata[]">
          Additional metadata for the message.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the message creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the message was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the message was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="AssistantConversationContext[]">
      Array of conversation contexts.
    </ParamField>

    <ParamField type="Metric[]">
      Performance metrics for the conversation.
    </ParamField>

    <ParamField type="Metadata[]">
      Additional metadata for the conversation.
    </ParamField>

    <ParamField type="Argument[]">
      Arguments passed to the conversation.
    </ParamField>

    <ParamField type="Metadata[]">
      Configuration options for the conversation.
    </ParamField>

    <ParamField type="AssistantConversationRecording[]">
      Array of conversation recordings.

      <Expandable>
        <ParamField type="string">
          Pre-signed URL to access the assistant audio recording.
        </ParamField>

        <ParamField type="string">
          Pre-signed URL to access the user audio recording.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="uint64">
      Identifier of the conversation creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the conversation was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the conversation was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Paginated">
  Pagination information for the response.

  <Expandable>
    <ParamField type="uint32">
      Current page number.
    </ParamField>

    <ParamField type="uint32">
      Number of items per page.
    </ParamField>

    <ParamField type="uint32">
      Total number of pages available.
    </ParamField>

    <ParamField type="uint64">
      Total number of items across all pages.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Technical error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant Knowledge
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-knowledge



Retrieves detailed information about a specific assistant's knowledge configuration using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantKnowledgeRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant knowledge configuration to retrieve.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the assistant associated with the knowledge configuration.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantKnowledgeRequest,
      get_assistant_knowledge,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_assistant_knowledge(
      client_cfg=connection_config,
      request=GetAssistantKnowledgeRequest(
          id="{assistant_knowledge_id}", assistantId="{assistant_id}"
      ),
  )
  pprint(response)

  ```

  ```go Go theme={null}

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve assistant knowledge configuration
  	response, err := clients.GetAssistantKnowledge(context.Background(), connectionConfig, &rapida_proto.GetAssistantKnowledgeRequest{
  		AssistantId: 3456789876541212,
  		Id:          567898765456788765,
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantKnowledge,
    GetAssistantKnowledgeRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantKnowledge(connectionCfg, 45678903456789, 12345676543211);
  })();


  async function getAssistantKnowledge(connectionCfg, assistantId, knowledgeId) {
    const request = new GetAssistantKnowledgeRequest();
    request.setAssistantId(assistantId);
    request.setId(knowledgeId);

    try {
      const response = await GetAssistantKnowledge(connectionCfg, request);
      console.log("Assistant Knowledge Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantKnowledge call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantKnowledge">
  Detailed information about the assistant's knowledge configuration.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant knowledge configuration.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated knowledge base.
    </ParamField>

    <ParamField type="boolean">
      Whether the reranker is enabled for knowledge retrieval.
    </ParamField>

    <ParamField type="uint32">
      Maximum number of top results to retrieve from the knowledge base.
    </ParamField>

    <ParamField type="float32">
      Minimum similarity score threshold for knowledge retrieval.
    </ParamField>

    <ParamField type="Knowledge">
      Detailed information about the associated knowledge base.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the knowledge base.
        </ParamField>

        <ParamField type="string">
          Name of the knowledge base.
        </ParamField>

        <ParamField type="string">
          Description of the knowledge base.
        </ParamField>

        <ParamField type="string">
          Visibility setting of the knowledge base.
        </ParamField>

        <ParamField type="string">
          Language of the knowledge base content.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the embedding model provider.
        </ParamField>

        <ParamField type="string">
          Name of the embedding model provider.
        </ParamField>

        <ParamField type="Metadata[]">
          Array of embedding model configuration options.

          <Expandable>
            <ParamField type="uint64">
              Unique identifier for the metadata entry.
            </ParamField>

            <ParamField type="string">
              The option key name.
            </ParamField>

            <ParamField type="string">
              The option value.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Current status of the knowledge base.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the knowledge base creator.
        </ParamField>

        <ParamField type="User">
          User object of the knowledge base creator.
        </ParamField>

        <ParamField type="uint64">
          Identifier of the last updater.
        </ParamField>

        <ParamField type="User">
          User object of the last updater.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the knowledge base was created.
        </ParamField>

        <ParamField type="timestamp">
          Timestamp when the knowledge base was last updated.
        </ParamField>

        <ParamField type="uint64">
          Associated organization identifier.
        </ParamField>

        <ParamField type="uint64">
          Associated project identifier.
        </ParamField>

        <ParamField type="Organization">
          Organization details associated with the knowledge base.
        </ParamField>

        <ParamField type="Tag">
          Tag information associated with the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Total number of documents in the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Total number of tokens in the knowledge base.
        </ParamField>

        <ParamField type="uint32">
          Total number of words in the knowledge base.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Method used for retrieving knowledge from the knowledge base.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the reranker model provider.
    </ParamField>

    <ParamField type="string">
      Name of the reranker model provider.
    </ParamField>

    <ParamField type="Metadata[]">
      Array of reranker configuration options.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the metadata entry.
        </ParamField>

        <ParamField type="string">
          The option key name.
        </ParamField>

        <ParamField type="string">
          The option value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant knowledge configuration was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the assistant knowledge configuration was last updated.
    </ParamField>

    <ParamField type="string">
      Current status of the assistant knowledge configuration.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant Tool
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-tool



Retrieves detailed information about a specific assistant tool using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantToolRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the assistant tool to retrieve.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the assistant that owns the tool.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantToolRequest,
      get_assistant_tool,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_assistant_tool(
      client_cfg=connection_config,
      request=GetAssistantToolRequest(
          id="{assistant_tool_id}", assistantId="{assistant_id}"
      ),
  )
  pprint(response)

  ```

  ```go Go theme={null}

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve assistant tool information
  	response, err := clients.GetAssistantTool(context.Background(), connectionConfig, &rapida_proto.GetAssistantToolRequest{
  		AssistantId: 3456789876541212,
  		Id:          567898765456788765,
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantTool,
    GetAssistantToolRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantTool(connectionCfg, 45678903456789);
  })();


  async function getAssistantTool(connectionCfg, assistantId, toolId) {
    const request = new GetAssistantToolRequest();
    request.setAssistantId(assistantId);
    request.setId(toolId);

    try {
      const response = await GetAssistantTool(connectionCfg, request);
      console.log("Assistant Tool Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantTool call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantTool">
  Detailed information about the assistant tool.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the assistant tool.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant that owns this tool.
    </ParamField>

    <ParamField type="string">
      Name of the assistant tool.
    </ParamField>

    <ParamField type="string">
      Description of the tool's functionality.
    </ParamField>

    <ParamField type="Struct">
      Tool fields configuration as a structured object.
    </ParamField>

    <ParamField type="string">
      Method used for tool execution.
    </ParamField>

    <ParamField type="Metadata[]">
      Array of execution configuration options.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the metadata entry.
        </ParamField>

        <ParamField type="string">
          The option key name.
        </ParamField>

        <ParamField type="string">
          The option value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Current status of the tool.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the tool was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the tool was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant Webhook
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-webhook



Retrieves detailed information about a specific webhook configured for an assistant using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantWebhookRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the webhook to retrieve.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the assistant that owns the webhook.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantWebhookRequest,
      get_assistant_webhook,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(
          "{rapida-api-key}"
      )
  )
  response = get_assistant_webhook(
      client_cfg=connection_config,
      request=GetAssistantWebhookRequest(
          id="{assistant_webhook_id}", assistantId="{assistant_id}"
      ),
  )
  pprint(response)

  ```

  ```go Go theme={null}
  package main
  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve webhook information
  	response, err := clients.GetAssistantWebhook(context.Background(), connectionConfig, &rapida_proto.GetAssistantWebhookRequest{
  		AssistantId: 3456789876541212,
  		Id:          567898765456788765,
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantWebhook,
    GetAssistantWebhookRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantWebhook(45678903456789, 12345676543211);
  })();

  async function getAssistantWebhook(connectionCfg, assistantId, webhookId) {
    const request = new GetAssistantWebhookRequest();
    request.setAssistantId(assistantId);
    request.setId(webhookId);

    try {
      const response = await GetAssistantWebhook(connectionCfg, request);
      console.log("Assistant Webhook Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantWebhook call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWebhook">
  Detailed information about the assistant webhook.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the webhook.
    </ParamField>

    <ParamField type="string[]">
      Array of call, WebRTC, or conversation event names that trigger this webhook.
    </ParamField>

    <ParamField type="string">
      Description of the webhook's purpose and functionality.
    </ParamField>

    <ParamField type="string">
      Webhook provider. HTTP webhooks use `http`.
    </ParamField>

    <ParamField type="Metadata[]">
      Delivery options for the webhook.

      <Expandable>
        <ResponseField name="http_method" type="string">
          HTTP method used for delivery. Supported values are `POST`, `PUT`, and `PATCH`.
        </ResponseField>

        <ResponseField name="http_url" type="string">
          Target URL where webhook requests are sent.
        </ResponseField>

        <ResponseField name="http_headers" type="string">
          JSON object containing HTTP headers included with each request.
        </ResponseField>

        <ResponseField name="retry_status_codes" type="string">
          JSON array of response status entries used by the delivery retry policy.
        </ResponseField>

        <ResponseField name="max_retry_count" type="string">
          Maximum number of retry attempts after a retryable failure.
        </ResponseField>

        <ResponseField name="timeout_seconds" type="string">
          Maximum time in seconds to wait for the webhook endpoint to respond.
        </ResponseField>
      </Expandable>
    </ParamField>

    <ParamField type="uint32">
      Priority level for webhook execution when multiple webhooks are triggered.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the assistant that owns this webhook.
    </ParamField>

    <ParamField type="string">
      Current status of the webhook (e.g., "active", "inactive").
    </ParamField>

    <ParamField type="uint64">
      Identifier of the user who created the webhook.
    </ParamField>

    <ParamField type="User">
      User object representing the creator of the webhook.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the user who last updated the webhook.
    </ParamField>

    <ParamField type="User">
      User object representing the last updater of the webhook.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the webhook was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the webhook was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code for machine-readable error handling.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Technical error message for debugging purposes.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message for user display.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Assistant HTTP Log
Source: https://doc.rapida.ai/api-reference/assistant/get-assistant-webhook-log



Retrieves a specific assistant HTTP log entry, including webhook delivery logs, by its ID using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

### Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantHTTPLogRequest">
  <Expandable>
    <ParamField type="uint64">
      The project identifier for scope filtering.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the HTTP log to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAssistantHTTPLogRequest,
      get_assistant_http_log,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{rapida-api-key}")
  )
  response = get_assistant_http_log(
      client_cfg=connection_config,
      request=GetAssistantHTTPLogRequest(
          id="{assistant_http_log_id}", projectId="{project_id}"
      ),
  )
  pprint(response)

  ```

  ```go Go theme={null}

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL")))

  	// Retrieve specific HTTP log
  	response, err := clients.GetAssistantHTTPLog(context.Background(), connectionConfig, &rapida_proto.GetAssistantHTTPLogRequest{
  		Id: 567898765456788765,
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAssistantHTTPLog,
    GetAssistantHTTPLogRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAssistantHTTPLog(connectionCfg, 45678903456789);
  })();


  async function getAssistantHTTPLog(connectionCfg, httpLogId) {
    const request = new GetAssistantHTTPLogRequest();
    request.setId(httpLogId);

    try {
      const response = await GetAssistantHTTPLog(connectionCfg, request);
      console.log("Assistant HTTP Log Response:", response.toObject());
    } catch (error) {
      console.error("Error with GetAssistantHTTPLog call:", error);
    }
  }

  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantHTTPLog">
  The assistant HTTP log entry details.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the HTTP log.
    </ParamField>

    <ParamField type="uint64">
      Source record identifier. For webhook deliveries, this is the webhook ID.
    </ParamField>

    <ParamField type="object">
      The request payload sent to the webhook.
    </ParamField>

    <ParamField type="object">
      The response received from the webhook.
    </ParamField>

    <ParamField type="string">
      Status of the webhook execution.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was last updated.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated assistant.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated project.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated organization.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the associated conversation.
    </ParamField>

    <ParamField type="string">
      Asset prefix used for the webhook.
    </ParamField>

    <ParamField type="string">
      Event type that triggered the HTTP request, such as a call, WebRTC, or conversation webhook event.
    </ParamField>

    <ParamField type="uint64">
      HTTP response status code from the webhook.
    </ParamField>

    <ParamField type="uint64">
      Time taken for the webhook execution in milliseconds.
    </ParamField>

    <ParamField type="uint32">
      Number of retry attempts made.
    </ParamField>

    <ParamField type="string">
      HTTP method used for the webhook request.
    </ParamField>

    <ParamField type="string">
      URL that was called for the webhook.
    </ParamField>

    <ParamField type="string">
      Source category for the HTTP log.
    </ParamField>

    <ParamField type="string">
      Context identifier associated with the source event, when available.
    </ParamField>

    <ParamField type="string">
      Delivery error message, when the HTTP request fails.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="uint64">
      Numeric error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Debugger Deployment
Source: https://doc.rapida.ai/api-reference/assistant/get-debugger-deployment

Get an assistant debugger deployment from the Rapida SDK.

Gets the latest debugger deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantDeploymentRequest">
  Deployment lookup request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantDebuggerDeployment,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");

  const response = await GetAssistantDebuggerDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantDebuggerDeployment,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);

  const response = await GetAssistantDebuggerDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAssistantDebuggerDeployment(
      GetAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAssistantDebuggerDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting debugger deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("get debugger deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantDebuggerDeployment">
  Debugger deployment. If no deployment exists, the deployment field may be omitted.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the debugger deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                      |
| --------- | -------------------------------------------- |
| `1009001` | Unauthenticated request.                     |
| `1009002` | Missing authentication scope.                |
| `1009003` | Invalid `assistantId`.                       |
| `1009004` | Unable to get assistant debugger deployment. |


# Get Phone Deployment
Source: https://doc.rapida.ai/api-reference/assistant/get-phone-deployment

Get an assistant phone deployment from the Rapida SDK.

Gets the latest phone deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantDeploymentRequest">
  Deployment lookup request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantPhoneDeployment,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");

  const response = await GetAssistantPhoneDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantPhoneDeployment,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);

  const response = await GetAssistantPhoneDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAssistantPhoneDeployment(
      GetAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAssistantPhoneDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting phone deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("get phone deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantPhoneDeployment">
  Phone deployment. If no deployment exists, the deployment field may be omitted.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the phone deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific options.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                   |
| --------- | ----------------------------------------- |
| `1010001` | Unauthenticated request.                  |
| `1010002` | Missing authentication scope.             |
| `1010003` | Invalid `assistantId`.                    |
| `1010004` | Unable to get assistant phone deployment. |


# Get Webplugin Deployment
Source: https://doc.rapida.ai/api-reference/assistant/get-webplugin-deployment

Get an assistant web plugin deployment from the Rapida SDK.

Gets the latest web plugin deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantDeploymentRequest">
  Deployment lookup request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantWebpluginDeployment,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");

  const response = await GetAssistantWebpluginDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantWebpluginDeployment,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);

  const response = await GetAssistantWebpluginDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAssistantWebpluginDeployment(
      GetAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAssistantWebpluginDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting web plugin deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("get web plugin deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWebpluginDeployment">
  Webplugin deployment. If no deployment exists, the deployment field may be omitted.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the web plugin deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string[]">
      Suggested starter prompts.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="boolean">
      Whether this web plugin capability is enabled.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                        |
| --------- | ---------------------------------------------- |
| `1012001` | Unauthenticated request.                       |
| `1012002` | Missing authentication scope.                  |
| `1012003` | Invalid `assistantId`.                         |
| `1012004` | Unable to get assistant web plugin deployment. |


# Get WhatsApp Deployment
Source: https://doc.rapida.ai/api-reference/assistant/get-whatsapp-deployment

Get an assistant WhatsApp deployment from the Rapida SDK.

Gets the latest WhatsApp deployment for an assistant. Use user-scoped authentication because the operation requires organization and project context.

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAssistantDeploymentRequest">
  Deployment lookup request.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantWhatsappDeployment,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");

  const response = await GetAssistantWhatsappDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    GetAssistantDeploymentRequest,
    GetAssistantWhatsappDeployment,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new GetAssistantDeploymentRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);

  const response = await GetAssistantWhatsappDeployment(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import ConnectionConfig
  from rapida.clients.protos.assistant_deployment_pb2 import (
      GetAssistantDeploymentRequest,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = connection_config.assistant_deployment_client.GetAssistantWhatsappDeployment(
      GetAssistantDeploymentRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
      ),
      metadata=connection_config.auth,
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	response, err := clients.GetAssistantWhatsappDeployment(
  		context.Background(),
  		connectionConfig,
  		&protos.GetAssistantDeploymentRequest{
  			AssistantId: 2227823180112723968,
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while getting WhatsApp deployment: %+v\n", err)
  		return
  	}
  	fmt.Printf("get WhatsApp deployment response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="AssistantWhatsappDeployment">
  WhatsApp deployment. If no deployment exists, the deployment field may be omitted.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the WhatsApp deployment.
    </ParamField>

    <ParamField type="uint64">
      Assistant ID for the deployment.
    </ParamField>

    <ParamField type="string">
      First message the assistant sends when the session starts.
    </ParamField>

    <ParamField type="boolean">
      Controls whether users can interrupt the opening greeting in audio sessions.
    </ParamField>

    <ParamField type="string">
      Message used when the assistant cannot understand or handle input.
    </ParamField>

    <ParamField type="double">
      Seconds to wait after interrupted or unclear input before asking the user to repeat.
    </ParamField>

    <ParamField type="string">
      Message sent when the assistant could not understand the user input.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Speech-to-text provider configuration.
    </ParamField>

    <ParamField type="DeploymentAudioProvider">
      Text-to-speech provider configuration.
    </ParamField>

    <ParamField type="string">
      Provider name.
    </ParamField>

    <ParamField type="Metadata[]">
      Provider-specific options.
    </ParamField>

    <ParamField type="string">
      Current deployment status.
    </ParamField>

    <ParamField type="uint64">
      Idle timeout in seconds.
    </ParamField>

    <ParamField type="uint64">
      Number of idle-timeout retries.
    </ParamField>

    <ParamField type="string">
      Message sent on idle timeout.
    </ParamField>

    <ParamField type="uint64">
      Maximum session duration in seconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the deployment was last updated.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Stable, machine-readable numeric code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end users.
    </ResponseField>
  </Expandable>
</ParamField>

## Errors

| Code      | Meaning                                      |
| --------- | -------------------------------------------- |
| `1013001` | Unauthenticated request.                     |
| `1013002` | Missing authentication scope.                |
| `1013003` | Invalid `assistantId`.                       |
| `1013004` | Unable to get assistant WhatsApp deployment. |


# Update Assistant Version
Source: https://doc.rapida.ai/api-reference/assistant/update-assistant-version

Promote an assistant provider version to the active assistant version.

Updates the active provider version for an assistant. Use this after creating a provider with [Create assistant provider](/api-reference/assistant/create-assistant-provider).

<Info>
  For setup and authentication options, see the [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="UpdateAssistantVersionRequest">
  Provider version to promote.

  <Expandable>
    <ParamField type="uint64">
      Assistant ID to update.
    </ParamField>

    <ParamField type="uint64">
      Provider version ID to make active.
    </ParamField>

    <ParamField type="string">
      Provider type for the version. Use `MODEL`, `AGENTKIT`, or `WEBSOCKET`.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    UpdateAssistantVersion,
    UpdateAssistantVersionRequest,
  } from "@rapidaai/react";

  const auth = ConnectionConfig.WithDebugger({
    authorization: "AUTHORIZATION_TOKEN_PLACEHOLDER",
    userId: "AUTH_ID_PLACEHOLDER",
    projectId: "PROJECT_ID_PLACEHOLDER",
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new UpdateAssistantVersionRequest();
  request.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  request.setAssistantproviderid("PROVIDER_VERSION_ID_PLACEHOLDER");
  request.setAssistantprovider("AGENTKIT");

  const response = await UpdateAssistantVersion(connectionCfg, request);
  console.dir(response.toObject());
  ```

  ```javascript Node.js theme={null}
  import {
    ConnectionConfig,
    UpdateAssistantVersion,
    UpdateAssistantVersionRequest,
  } from "@rapidaai/nodejs";

  const auth = ConnectionConfig.WithDebugger({
    authorization: process.env.RAPIDA_AUTHORIZATION,
    userId: process.env.RAPIDA_AUTH_ID,
    projectId: process.env.RAPIDA_PROJECT_ID,
  });
  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(auth);

  const request = new UpdateAssistantVersionRequest();
  request.setAssistantid(process.env.RAPIDA_ASSISTANT_ID);
  request.setAssistantproviderid(process.env.RAPIDA_PROVIDER_VERSION_ID);
  request.setAssistantprovider("AGENTKIT");

  try {
    const response = await UpdateAssistantVersion(connectionCfg, request);
    console.dir(response.toObject());
  } catch (error) {
    console.error("Error with UpdateAssistantVersion call:", error);
  }
  ```

  ```python Python theme={null}
  import os
  from pprint import pprint

  from rapida import (
      ConnectionConfig,
      UpdateAssistantVersionRequest,
      update_assistant_version,
  )

  auth = ConnectionConfig.with_debugger(
      authorization=os.getenv("RAPIDA_AUTHORIZATION"),
      user_id=os.getenv("RAPIDA_AUTH_ID"),
      project_id=os.getenv("RAPIDA_PROJECT_ID"),
  )
  connection_config = ConnectionConfig.default_connection_config(auth)

  response = update_assistant_version(
      client_cfg=connection_config,
      request=UpdateAssistantVersionRequest(
          assistantId=int(os.getenv("RAPIDA_ASSISTANT_ID")),
          assistantProviderId=int(os.getenv("RAPIDA_PROVIDER_VERSION_ID")),
          assistantProvider="AGENTKIT",
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/rapidaai/rapida-go/rapida/clients"
  	"github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithPersonalToken(
  			os.Getenv("RAPIDA_AUTHORIZATION"),
  			os.Getenv("RAPIDA_AUTH_ID"),
  			os.Getenv("RAPIDA_PROJECT_ID"),
  		),
  	)

  	request := &protos.UpdateAssistantVersionRequest{
  		AssistantId:         2227823180112723968,
  		AssistantProviderId: 2230142097179373568,
  		AssistantProvider:   "AGENTKIT",
  	}

  	response, err := clients.UpdateAssistantVersion(context.Background(), connectionConfig, request)
  	if err != nil {
  		fmt.Printf("error while updating assistant version: %+v\n", err)
  		return
  	}
  	fmt.Printf("update assistant version response: %+v\n", response)
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Assistant">
  Updated assistant with the active provider version.
</ParamField>

<ParamField type="Error">
  Error details when the operation fails.
</ParamField>


# Authentication
Source: https://doc.rapida.ai/api-reference/authentication

Authentication and connection to use SDK

Use `ConnectionConfig` to configure authentication and endpoints for all SDK clients.

<CodeGroup>
  ```ts TypeScript / Node.js theme={null}
  import { ConnectionConfig } from "@rapidaai/nodejs";

  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({ ApiKey: process.env.RAPIDA_API_KEY })
  );
  ```

  ```javascript React theme={null}
  import { ConnectionConfig } from "@rapidaai/react";

  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({ ApiKey: process.env.RAPIDA_API_KEY })
  );
  ```

  ```go Go theme={null}

  import (
    "os"
    "github.com/rapidaai/rapida-go/rapida/connections"
  )

  connectionConfig := connections.DefaultconnectionConfig(
      connections.WithSDK(
          os.Getenv("RAPIDA_API_KEY"),
      ),
  )
  ```

  ```python Python theme={null}
  import os
  from rapida import ConnectionConfig

  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(api_key=os.getenv("RAPIDA_API_KEY"))
  )
  ```
</CodeGroup>

#### PersonalToken

* Use for backend-only or administrative operations where a human- or service-owned token is appropriate (e.g., CI/CD, provisioning, migrations).
* Best when you need elevated privileges across projects or organization-level APIs.
* Never embed in client-side code. Store securely (vault/secret manager) and rotate regularly.

  <ResponseField name="Authorization" type="string">
    Personal token for administrative APIs.
  </ResponseField>

  <ResponseField name="AuthId" type="string">
    Rapida Auth ID performing the action.
  </ResponseField>

  <ResponseField name="ProjectId" type="string">
    Rapida project ID for scoping requests.
  </ResponseField>

<CodeGroup>
  ```ts TypeScript / Node.js theme={null}
  import { ConnectionConfig } from "@rapidaai/nodejs";
  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithPersonalToken({
      Authorization: RAPIDA_AUTHORIZATION_TOKEN,
      AuthId: RAPIDA_AUTH_ID,
      ProjectId: RAPIDA_PROJECT_ID,
    })
  );
  ```

  ```javascript React theme={null}
  import { ConnectionConfig } from "@rapidaai/react";
  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithPersonalToken({
      Authorization: RAPIDA_AUTHORIZATION_TOKEN,
      AuthId: RAPIDA_AUTH_ID,
      ProjectId: RAPIDA_PROJECT_ID,
    })
  );
  ```

  ```go Go theme={null}

  import (
    "os"
    "github.com/rapidaai/rapida-go/rapida/connections"
  )

  connectionConfig := connections.DefaultconnectionConfig(
      connections.WithPersonalToken(
          os.Getenv("RAPIDA_AUTHORIZATION_TOKEN"),
          os.Getenv("RAPIDA_AUTH_ID"),
          os.Getenv("RAPIDA_PROJECT_ID"),
      ),
  )
  ```

  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
  )

  connectionConfig = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_personal_token(
          authorization="RAPIDA_AUTHORIZATION_TOKEN",
          auth_id="RAPIDA_AUTH_ID",
          project_id="RAPIDA_PROJECT_ID",
      )
  )
  ```
</CodeGroup>

#### WithSDK

* Use for typical application integrations (server-side web apps, backend services) using a project-scoped API key.
* Safer to use in application servers than personal tokens; permissions are limited to the project.
* Do not ship in public client apps without a proxy; prefer server-to-server.

  <ResponseField name="ApiKey" type="string">
    Project API key used for typical app integrations.
  </ResponseField>

  <ResponseField name="UserId" type="string">
    Optional user identifier to propagate in requests.
  </ResponseField>

<CodeGroup>
  ```ts TypeScript / Node.js theme={null}
  import { ConnectionConfig } from "@rapidaai/nodejs";
  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({ ApiKey: process.env.RAPIDA_API_KEY })
  );
  ```

  ```javascript React theme={null}
  import { ConnectionConfig } from "@rapidaai/react";
  const connection = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({ ApiKey: process.env.RAPIDA_API_KEY })
  );
  ```

  ```go Go theme={null}

  import (
    "os"
    "github.com/rapidaai/rapida-go/rapida/connections"
  )

  connectionConfig := connections.DefaultconnectionConfig(
      connections.WithSDK(
          os.Getenv("RAPIDA_API_KEY"),
      ),
  )
  ```

  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
  )


  connectionConfig = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(
          api_key="API_KEY"
      )
  )
  ```
</CodeGroup>


# Create Bulk Phone Calls
Source: https://doc.rapida.ai/api-reference/call/create-bulk-call



Creates multiple outbound phone calls in a single request using your configured assistant.

<Info>
  For full setup and authentication options, see the Installation guide: [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreateBulkPhoneCallRequest">
  <Expandable>
    <ParamField type="CreatePhoneCallRequest[]">
      <Expandable>
        <ParamField type="AssistantDefinition">
          Assistant definition used for each call.

          <Expandable>
            <ParamField type="string">
              Assistant ID to use for the call.
            </ParamField>

            <ParamField type="string">
              Assistant version. Use `latest` to run the latest published version.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Destination phone number in E.164 format (for example, +14155550123).
        </ParamField>

        <ParamField type="string">
          Caller ID phone number to originate the call from (E.164 format). If omitted, the system default will be used.
        </ParamField>

        <ParamField type="Map<string, google_protobuf_any_pb.Any>">
          Additional arguments passed to the call as a key-value map.
        </ParamField>

        <ParamField type="Map<string, google_protobuf_any_pb.Any>">
          Runtime overrides for this call. Use namespaced keys such as `experience.*`, `listen.*`, `speak.*`, `speaker.*`, `model.*`, or `agentkit.*`.
        </ParamField>

        <ParamField type="Map<string, google_protobuf_any_pb.Any>">
          Arbitrary metadata to associate with the call for tracking and analytics.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Runtime options

Each item in `phoneCalls` is a `CreatePhoneCallRequest`, so each recipient can receive different runtime overrides.

```json theme={null}
{
  "phoneCalls": [
    {
      "assistant": {
        "assistantId": "2230142097179373568",
        "version": "latest"
      },
      "toNumber": "+14155550123",
      "args": {
        "name": "Jane"
      },
      "options": {
        "experience.greeting": "Hi {{name}}, this is Rapida calling about your appointment.",
        "listen.language": "en",
        "speak.voice.id": "VOICE_ID_PLACEHOLDER"
      }
    }
  ]
}
```

See [Create Phone Call](/api-reference/call/create-call#runtime-options) for supported option groups and links to the detailed option references.

### Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    AssistantDefinition,
    CreateBulkPhoneCall,
    ConnectionConfig,
    CreateBulkPhoneCallRequest,
    CreatePhoneCallRequest,
  } from '@rapidaai/react';

  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({ ApiKey: "YOUR_API_KEY_PLACEHOLDER" })
  );
  const phoneCallRequest = new CreatePhoneCallRequest();
  const assistant = new AssistantDefinition();
  assistant.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  assistant.setVersion("latest");
  phoneCallRequest.setAssistant(assistant);
  phoneCallRequest.setTonumber("TO_NUMBER_PLACEHOLDER");

  const bulkPhoneCallRequest = new CreateBulkPhoneCallRequest();
  bulkPhoneCallRequest.addPhonecalls(phoneCallRequest);
  CreateBulkPhoneCall(connectionCfg, bulkPhoneCallRequest)
    .then((x) => {
      if (x.getSuccess()) {
        console.dir(x.getData().toObject());
        return;
      }
      const err = x.getError();
      if (err?.getHumanmessage()) console.error(err.getHumanmessage());
    })
    .catch((x) => {
      console.dir(x);
    });

  ```

  ```javascript Node.js theme={null}
  import {
    AssistantDefinition,
    CreateBulkPhoneCall,
    ConnectionConfig,
    CreateBulkPhoneCallRequest,
    CreatePhoneCallRequest,
  } from "@rapidaai/nodejs";

  let connectionCfg = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({
      ApiKey: "YOUR_API_KEY_PLACEHOLDER",
    })
  );
  const phoneCallRequest = new CreatePhoneCallRequest();
  // define assistant
  const assistant = new AssistantDefinition();
  assistant.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  assistant.setVersion("latest");
  phoneCallRequest.setAssistant(assistant);
  phoneCallRequest.setTonumber("TO_NUMBER_PLACEHOLDER");

  const bulkPhoneCallRequest = new CreateBulkPhoneCallRequest();
  bulkPhoneCallRequest.addPhonecalls(phoneCallRequest);
  CreateBulkPhoneCall(connectionCfg, bulkPhoneCallRequest)
    .then((x) => {
      if (x.getSuccess()) {
        console.dir(x.getData().toObject());
        return;
      }
      const err = x.getError();
      if (err?.getHumanmessage()) console.error(err.getHumanmessage());
    })
    .catch((x) => {
      console.dir(x);
    });

  ```

  ```python Python theme={null}
  import os
  from rapida import (
      ConnectionConfig,
      create_bulk_phone_call,
      CreatePhoneCallRequest,
      CreateBulkPhoneCallRequest,
      AssistantDefinition,
  )
  from pprint import pprint

  connectionConfig = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(os.getenv("RAPIDA_API_KEY"))
  )
  call = CreatePhoneCallRequest(
      assistant=AssistantDefinition(
          assistantId=2230142097179373568,
          version="latest",
      ),
      toNumber="+14155550123",
  )
  response = create_bulk_phone_call(
      client_cfg=connectionConfig,
      request=CreateBulkPhoneCallRequest(
          phoneCalls=[call],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {

  	// for more authentication check https://doc.rapida.ai/api-reference/authentication
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_API_KEY")))
  	response, err := clients.CreateBulkPhoneCall(context.Background(), connectionConfig, &protos.CreateBulkPhoneCallRequest{
  		PhoneCalls: []*protos.CreatePhoneCallRequest{
  			{
  				Assistant: &protos.AssistantDefinition{
  					AssistantId: 2227823180112723968,
  					Version:     "latest",
  				},
  				ToNumber: "+14155550123",
  			}},
  	})

  	if err != nil {
  		fmt.Printf("error while creating bulk phone calls: %+v\n", err)
  		return
  	}
  	fmt.Printf("create bulk phone calls response: %+v\n", response)
  }

  ```
</CodeGroup>

### Response

<ParamField type="int">
  Numeric status code for the operation
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful
</ParamField>

<ParamField type="Error">
  <Expandable>
    <ResponseField name="errorCode" type="string (uint64)">
      Stable, machine-readable numeric code. Represented as a string in JS/TS; parse only if you need numeric comparisons.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details. Avoid showing directly to end-users.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end-users. Localize in your app if needed.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="AssistantConversation[]">
  <Expandable>
    <ParamField type="string">
      Unique identifier for the conversation instance.
    </ParamField>

    <ParamField type="string">
      Identifier for the Assistant associated with this conversation.
    </ParamField>

    <ParamField type="string">
      Project ID associated with this conversation.
    </ParamField>

    <ParamField type="string">
      Organization ID related to the conversation.
    </ParamField>

    <ParamField type="string">
      Source of the conversation (e.g., "phone-call").
    </ParamField>

    <ParamField type="string">
      Identifier for the assistant provider model used in the conversation.
    </ParamField>

    <ParamField type="string">
      Unique identifier string for tracking this conversation.
    </ParamField>

    <ParamField type="string">
      Indicates the current status of the conversation (e.g., "ACTIVE").
    </ParamField>

    <ParamField type="google.protobuf.Timestamp">
      Timestamp indicating when the conversation was created.
    </ParamField>

    <ParamField type="google.protobuf.Timestamp">
      Timestamp indicating the last update to the conversation.
    </ParamField>

    <ParamField type="Map<string, string>" description="Key-value pairs of metadata associated with the call.">
      <Expandable>
        <ParamField type="string">
          Metadata key (e.g., "talk.outgoing\_api\_response", "talk.client").
        </ParamField>

        <ParamField type="string">
          Metadata value, often a JSON string containing detailed data (e.g., account details, client information).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>


# Create Phone Call
Source: https://doc.rapida.ai/api-reference/call/create-call



Creates an outbound phone call to the specified number using your configured assistant.

<Info>
  For full setup and authentication options, see the Installation guide: [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="CreatePhoneCallRequest">
  <Expandable>
    <ParamField type="AssistantDefinition">
      Assistant definition used for the call.

      <Expandable>
        <ParamField type="string">
          Assistant ID to use for the call.
        </ParamField>

        <ParamField type="string">
          Assistant version. Use `latest` to run the latest published version.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Destination phone number in E.164 format (for example, +14155550123).
    </ParamField>

    <ParamField type="string">
      Caller ID phone number to originate the call from (E.164 format). If omitted, the system default will be used.
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Additional arguments passed to the call as a key-value map.
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Runtime overrides for this call. Use namespaced keys such as `experience.*`, `listen.*`, `speak.*`, `speaker.*`, `model.*`, or `agentkit.*`.
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Arbitrary metadata to associate with the call for tracking and analytics.
    </ParamField>
  </Expandable>
</ParamField>

## Runtime options

Use `options` to override saved assistant and deployment settings for one outbound call. Runtime options do not update the assistant version or Phone Call deployment.

```json theme={null}
{
  "assistant": {
    "assistantId": "2230142097179373568",
    "version": "latest"
  },
  "toNumber": "+14155550123",
  "fromNumber": "+14155550100",
  "args": {
    "name": "Jane"
  },
  "options": {
    "experience.greeting": "Hi {{name}}, this is Rapida calling about your appointment.",
    "experience.greeting_interruptible": false,
    "listen.language": "en",
    "listen.model": "nova-3",
    "speak.voice.id": "VOICE_ID_PLACEHOLDER",
    "speak.language": "en",
    "model.name": "gpt-4o-mini"
  }
}
```

| Option group            | What it overrides                                                                                          | Reference                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `experience.*`          | Greeting, idle timeout, error message, and maximum session duration for this call.                         | [Experience](/assistants/configuration/experience#runtime-overrides)     |
| `listen.*`              | Speech-to-text, language, model, audio format, and provider-specific transcription settings.               | [Listen](/assistants/configuration/listen#runtime-overrides)             |
| `speak.*` / `speaker.*` | Text-to-speech voice, language, model, audio format, pronunciation, pauses, and ambient audio.             | [Speak](/assistants/configuration/speak#runtime-overrides)               |
| `model.*`               | Model provider options for this call, such as model name, temperature, credential, or connection settings. | [Create Assistant](/assistants/create-assistant#runtime-model-overrides) |
| `agentkit.*`            | AgentKit connection policy and metadata for this call.                                                     | [AgentKit](/assistants/agentkit#runtime-overrides)                       |

<Tip>
  Use `args` for prompt and greeting variables, such as `{{name}}`. Use `options` for runtime configuration overrides, such as `experience.greeting`, `listen.model`, or `speak.voice.id`.
</Tip>

### Usage

<CodeGroup>
  ```ts React theme={null}
  import {
    ConnectionConfig,
    CreatePhoneCall,
    AssistantDefinition,
    CreatePhoneCallRequest,
  } from '@rapidaai/react';

  const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({
      ApiKey: "YOUR_API_KEY_PLACEHOLDER",
    })
  );

  const phoneCallRequest = new CreatePhoneCallRequest();
  const assistant = new AssistantDefinition();
  assistant.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  assistant.setVersion("latest");
  phoneCallRequest.setAssistant(assistant);
  phoneCallRequest.setFromnumber("FROM_NUMBER_PLACEHOLDER");
  phoneCallRequest.setTonumber("TO_NUMBER_PLACEHOLDER");

  CreatePhoneCall(connectionCfg, phoneCallRequest)
  .then(x => {
      console.log(x);
      if (x.getSuccess()) {
      return;
      }
      const err = x.getError();
      if (err?.getHumanmessage()) console.error(err.getHumanmessage());
  })
  .catch(x => {
      console.dir(x);
  });
  ```

  ```javascript Node.js theme={null}
  import {
    AssistantDefinition,
    CreatePhoneCall,
    ConnectionConfig,
    CreatePhoneCallRequest,
  } from "@rapidaai/nodejs";

  let connectionCfg = ConnectionConfig.DefaultConnectionConfig(
    ConnectionConfig.WithSDK({
      ApiKey: "YOUR_API_KEY_PLACEHOLDER",
    })
  );
  const phoneCallRequest = new CreatePhoneCallRequest();
  // define assistant
  const assistant = new AssistantDefinition();
  assistant.setAssistantid("ASSISTANT_ID_PLACEHOLDER");
  assistant.setVersion("latest");
  phoneCallRequest.setAssistant(assistant);
  phoneCallRequest.setTonumber("TO_NUMBER_PLACEHOLDER");

  CreatePhoneCall(connectionCfg, phoneCallRequest)
    .then((x) => {
      if (x.getSuccess()) {
        console.dir(x.getData().toObject());
        return;
      }
      const err = x.getError();
      if (err?.getHumanmessage()) console.error(err.getHumanmessage());
    })
    .catch((x) => {
      console.dir(x);
    });


  ```

  ```python Python theme={null}
  import os
  from rapida import (
      ConnectionConfig,
      create_phone_call,
      CreatePhoneCallRequest,
      AssistantDefinition,
  )
  from pprint import pprint

  connectionConfig = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk(os.getenv("RAPIDA_API_KEY"))
  )
  call = CreatePhoneCallRequest(
      assistant=AssistantDefinition(
          assistantId=2230142097179373568,
          version="latest",
      ),
      toNumber="+14155550123",
  )
  response = create_phone_call(client_cfg=connectionConfig, request=call)
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/rapidaai/rapida-go/rapida/clients"
  	"github.com/rapidaai/rapida-go/rapida/connections"
  	protos "github.com/rapidaai/rapida-go/protos"
  )

  func main() {
  	connectionConfig := connections.DefaultconnectionConfig(
  		connections.WithSDK(os.Getenv("RAPIDA_API_KEY")),
  	)
  	response, err := clients.CreatePhoneCall(
  		context.Background(),
  		connectionConfig,
  		&protos.CreatePhoneCallRequest{
  			Assistant: &protos.AssistantDefinition{
  				AssistantId: 2230142097179373568,
  				Version:     "latest",
  			},
  			ToNumber:   "+14155550123",
  			FromNumber: "+14155550124",
  		},
  	)
  	if err != nil {
  		fmt.Printf("error while creating phone call: %+v\n", err)
  		return
  	}
  	fmt.Printf("create phone call response: %+v\n", response)
  }
  ```
</CodeGroup>

### Response

<ParamField type="int">
  Numeric status code for the operation
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful
</ParamField>

<ParamField type="Error">
  <Expandable>
    <ResponseField name="errorCode" type="string (uint64)">
      Stable, machine-readable numeric code. Represented as a string in JS/TS; parse only if you need numeric comparisons.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented message with diagnostic details. Avoid showing directly to end-users.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      Human-friendly description safe for display to end-users. Localize in your app if needed.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="AssistantConversation">
  <Expandable>
    <ParamField type="string">
      Unique identifier for the conversation instance.
    </ParamField>

    <ParamField type="string">
      Identifier for the Assistant associated with this conversation.
    </ParamField>

    <ParamField type="string">
      Project ID associated with this conversation.
    </ParamField>

    <ParamField type="string">
      Organization ID related to the conversation.
    </ParamField>

    <ParamField type="string">
      Source of the conversation (e.g., "phone-call").
    </ParamField>

    <ParamField type="string">
      Identifier for the assistant provider model used in the conversation.
    </ParamField>

    <ParamField type="string">
      Unique identifier string for tracking this conversation.
    </ParamField>

    <ParamField type="string">
      Indicates the current status of the conversation (e.g., "ACTIVE").
    </ParamField>

    <ParamField type="google.protobuf.Timestamp">
      Timestamp indicating when the conversation was created.
    </ParamField>

    <ParamField type="google.protobuf.Timestamp">
      Timestamp indicating the last update to the conversation.
    </ParamField>

    <ParamField type="Map<string, string>" description="Key-value pairs of metadata associated with the call.">
      <Expandable>
        <ParamField type="string">
          Metadata key (e.g., "talk.outgoing\_api\_response", "talk.client").
        </ParamField>

        <ParamField type="string">
          Metadata value, often a JSON string containing detailed data (e.g., account details, client information).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>


# Get All Endpoints
Source: https://doc.rapida.ai/api-reference/endpoint/get-all-endpoint



Retrieves a paginated list of all endpoints with optional filtering criteria using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllEndpointRequest">
  <Expandable>
    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          The page number to retrieve (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of endpoints to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Criteria[]">
      Optional array of filtering criteria to apply to the endpoint search.

      <Expandable>
        <ParamField type="string">
          The field name to filter by.
        </ParamField>

        <ParamField type="string">
          The value to match against the specified key.
        </ParamField>

        <ParamField type="string">
          The logic operator for the criteria. Accepted values: "should" | "must"
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllEndpointRequest,
      get_all_endpoint
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )
  response = get_all_endpoint(
      client_cfg=connection_config,
      request=GetAllEndpointRequest(
          paginate=Paginate(page=0, pageSize=20),
          criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL"))).WithLocal()

  	// Retrieve all endpoints with pagination
  	response, err := clients.GetAllEndpoint(context.Background(), connectionConfig, &rapida_proto.GetAllEndpointRequest{
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "key",
  		// 	Value: "value",
  		// 	Logic: "should", // or "must"
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAllEndpoints,
    Paginate,
    Criteria,
    GetAllEndpointRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllEndpoints(connectionCfg)
  })();

  async function getAllEndpoints(connectionCfg) {
    const request = new GetAllEndpointRequest();

    let paginate = new Paginate();
    paginate.setPage(0);
    paginate.setPagesize(20);
    request.setPaginate(paginate);

    let criteria = new Criteria();
    criteria.setKey("KEY FOR FILTER");
    criteria.setValue("MATCHING _VAULE");
    criteria.setLogic("should" || "must");
    request.addCriterias(criteria);
    const response = await GetAllEndpoints(connectionCfg, request);
    if (response.getError()) {
      console.error(
        "Error fetching all endpoints:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("All Endpoints:", response.getData().toObject());
    }
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Endpoint[]">
  Array of endpoint objects returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the endpoint.
    </ParamField>

    <ParamField type="string">
      Operational status of the endpoint.
    </ParamField>

    <ParamField type="string">
      Visibility status of the endpoint.
    </ParamField>

    <ParamField type="string">
      Source of the endpoint.
    </ParamField>

    <ParamField type="uint64">
      Identifier mapping to the endpoint's source.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the endpoint provider.
    </ParamField>

    <ParamField type="string">
      Selected language configuration for the endpoint.
    </ParamField>

    <ParamField type="string">
      Name assigned to the endpoint.
    </ParamField>

    <ParamField type="string">
      Description of the endpoint's purpose.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp of endpoint creation.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp of last endpoint update.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Pagination information for the response.

  <Expandable>
    <ParamField type="int64">
      Total number of endpoints available.
    </ParamField>

    <ParamField type="int32">
      Total number of pages available.
    </ParamField>

    <ParamField type="int32">
      Current page number (0-based).
    </ParamField>

    <ParamField type="int32">
      Number of items per page.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are more pages available.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are previous pages available.
    </ParamField>
  </Expandable>
</ParamField>


# Get All Endpoint Logs
Source: https://doc.rapida.ai/api-reference/endpoint/get-all-endpoint-log



Retrieves a paginated list of all log entries for a specific endpoint with optional filtering criteria using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetAllEndpointLogRequest">
  <Expandable>
    <ParamField type="Paginate">
      Pagination configuration for the request.

      <Expandable>
        <ParamField type="uint32">
          The page number to retrieve (0-based indexing).
        </ParamField>

        <ParamField type="uint32">
          Number of endpoint logs to return per page.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the endpoint for which to retrieve all log entries.
    </ParamField>

    <ParamField type="Criteria[]">
      Optional array of filtering criteria to apply to the endpoint log search.

      <Expandable>
        <ParamField type="string">
          The field name to filter by.
        </ParamField>

        <ParamField type="string">
          The value to match against the specified key.
        </ParamField>

        <ParamField type="string">
          The logic operator for the criteria. Accepted values: "should" | "must"
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetAllEndpointLogRequest,
      get_all_endpoint_log
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )
  response = get_all_endpoint_log(
      client_cfg=connection_config,
      request=GetAllEndpointLogRequest(
          endpointId=2223006263292198912,
          paginate=Paginate(page=0, pageSize=20),
          # criterias=[Criteria(key="KEY", value="VALUE", logic="should")],
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL"))).WithLocal()

  	// Retrieve all endpoint logs with pagination for a specific endpoint
  	response, err := clients.GetAllEndpointLog(context.Background(), connectionConfig, &rapida_proto.GetAllEndpointLogRequest{
  		Paginate: &rapida_proto.Paginate{
  			Page:     0,
  			PageSize: 20,
  		},
  		EndpointId: 2223006263292198912,
  		// Optional: Add filtering criteria
  		// Criterias: []*rapida_proto.Criteria{{
  		// 	Key:   "key",
  		// 	Value: "value",
  		// 	Logic: "should", // or "must"
  		// }},
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetAllEndpointLog,
    Paginate,
    Criteria,
    GetAllEndpointLogRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getAllEndpointLogs(connectionCfg)
  })();
  async function getAllEndpointLogs(connectionCfg) {
    const request = new GetAllEndpointLogRequest();

    let paginate = new Paginate();
    paginate.setPage(0);
    paginate.setPagesize(20);
    request.setPaginate(paginate);

    let criteria = new Criteria();
    criteria.setKey("KEY FOR FILTER");
    criteria.setValue("MATCHING _VAULE");
    criteria.setLogic("should" || "must");
    request.addCriterias(criteria);
    const response = await GetAllEndpointLog(connectionCfg, request);

    if (response.getError()) {
      console.error(
        "Error fetching all endpoint logs:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("All Endpoint Logs:", response.getData().toObject());
    }
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="EndpointLog[]">
  Array of endpoint log objects returned by the request.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the endpoint log entry.
    </ParamField>

    <ParamField type="uint64">
      The identifier of the endpoint this log belongs to.
    </ParamField>

    <ParamField type="string">
      Source system or origin of the endpoint execution.
    </ParamField>

    <ParamField type="string">
      Current status of the endpoint execution.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the endpoint provider.
    </ParamField>

    <ParamField type="uint64">
      Time taken for the endpoint execution in milliseconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was last updated.
    </ParamField>

    <ParamField type="Metric[]">
      Array of performance and execution metrics.

      <Expandable>
        <ParamField type="string">
          Name of the metric.
        </ParamField>

        <ParamField type="string">
          Value of the metric.
        </ParamField>

        <ParamField type="string">
          Description of what the metric measures.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Metadata[]">
      Array of metadata associated with the endpoint execution.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the metadata entry.
        </ParamField>

        <ParamField type="string">
          The metadata key name.
        </ParamField>

        <ParamField type="string">
          The metadata value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Argument[]">
      Array of arguments passed to the endpoint during execution.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the argument.
        </ParamField>

        <ParamField type="string">
          Name of the argument.
        </ParamField>

        <ParamField type="string">
          Value of the argument.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Metadata[]">
      Array of execution options used for the endpoint.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the option entry.
        </ParamField>

        <ParamField type="string">
          The option key name.
        </ParamField>

        <ParamField type="string">
          The option value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Pagination information for the response.

  <Expandable>
    <ParamField type="int64">
      Total number of endpoint logs available.
    </ParamField>

    <ParamField type="int32">
      Total number of pages available.
    </ParamField>

    <ParamField type="int32">
      Current page number (0-based).
    </ParamField>

    <ParamField type="int32">
      Number of items per page.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are more pages available.
    </ParamField>

    <ParamField type="boolean">
      Indicates if there are previous pages available.
    </ParamField>
  </Expandable>
</ParamField>


# Get Endpoint
Source: https://doc.rapida.ai/api-reference/endpoint/get-endpoint



Retrieves data or executes operations on a specified endpoint using the Rapida API.

<Info>
  For full setup and authentication options, see the [Installation guide](/api-reference/installation).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetEndpointRequest">
  <Expandable>
    <ParamField type="uint64">
      A unique identifier for the endpoint. This is a mandatory field for the request.
    </ParamField>

    <ParamField type="uint64 (optional)">
      An optional identifier for the provider model associated with the endpoint.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetEndpointRequest,
      get_endpoint
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )
  response = get_endpoint(
      client_cfg=connection_config,
      request=GetEndpointRequest(id=2223006263292198912),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL"))).WithLocal()

  	// Provide the endpoint ID to fetch endpoint details
  	response, err := clients.GetEndpoint(context.Background(), connectionConfig, &rapida_proto.GetEndpointRequest{
  		Id: 2223006263292198912,
  	})

  	if err != nil {
  		fmt.Printf("Error while fetching endpoint details: %+v\n", err)
  		return
  	}

  	// Print the retrieved endpoint details
  	fmt.Printf("Endpoint details: Code: %d, Success: %t, Endpoint ID: %d\n", response.Code, response.Success, response.Data.Id)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetEndpoint,
    GetEndpointRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getEndpoint(connectionCfg)
  })();

  async function getEndpoint(connectionCfg) {
    const request = new GetEndpointRequest();
    // endpointId
    request.setId(2223006263292198912);

    const response = await GetEndpoint(connectionCfg, request);
    if (response.getError()) {
      console.error(
        "Error fetching endpoint details:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("Endpoint Details:", response.getData());
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="object">
  Detailed information about the endpoint.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the endpoint.
    </ParamField>

    <ParamField type="string">
      Operational status of the endpoint.
    </ParamField>

    <ParamField type="string">
      Visibility status of the endpoint.
    </ParamField>

    <ParamField type="string">
      Source of the endpoint.
    </ParamField>

    <ParamField type="uint64">
      Identifier mapping to the endpoint's source.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the endpoint provider.
    </ParamField>

    <ParamField type="string">
      Selected language configuration for the endpoint.
    </ParamField>

    <ParamField type="string">
      Name assigned to the endpoint.
    </ParamField>

    <ParamField type="string">
      Description of the endpoint's purpose.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp of endpoint creation.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp of last endpoint update.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the creator.
    </ParamField>

    <ParamField type="uint64">
      Identifier of the last updater.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Get Endpoint Log
Source: https://doc.rapida.ai/api-reference/endpoint/get-endpoint-log



Retrieves detailed log information for a specific endpoint execution using the Rapida API.

<Info>
  For more authentication options, see: [https://doc.rapida.ai/api-reference/authentication](https://doc.rapida.ai/api-reference/authentication)
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="GetEndpointLogRequest">
  <Expandable>
    <ParamField type="uint64">
      The unique identifier of the endpoint for which to retrieve log information.
    </ParamField>

    <ParamField type="uint64">
      The unique identifier of the specific endpoint log entry to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      GetEndpointLogRequest,
      get_endpoint_log
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )
  response = get_endpoint_log(
      client_cfg=connection_config,
      request=GetEndpointLogRequest(
          id=2230958607199895552,
          endpointId=2223006263292198912,
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  )

  func main() {
  	// Configure client connection using RAPIDA_PROJECT_CREDENTIAL environment variable
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK(os.Getenv("RAPIDA_PROJECT_CREDENTIAL"))).WithLocal()

  	// Retrieve endpoint log by endpoint ID and log ID
  	response, err := clients.GetEndpointLog(context.Background(), connectionConfig, &rapida_proto.GetEndpointLogRequest{
  		EndpointId: "ENDPOINT_ID",
  		Id:         "ENDPOINT_LOG_ID",
  	})

  	if err != nil {
  		fmt.Printf("Error while making call using rapida: %+v\n", err)
  		return
  	}

  	// Print the response
  	fmt.Printf("Rapida calling response: %+v\n", response)
  }
  ```

  ```typescript NodeJs theme={null}
  import {
    ConnectionConfig,
    GetEndpointLog,
    GetEndpointLogRequest,
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    getEndpointLog(connectionCfg)
  })();

  async function getEndpointLog(connectionCfg) {
    const request = new GetEndpointLogRequest();
    request.setId(2223006263292198912);
    request.setEndpointid(2223006263292198912);
    const response = await GetEndpointLog(connectionCfg, request);

    if (response.getError()) {
      console.error(
        "Error fetching endpoint log:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("Endpoint Log Details:", response.getData());
    }
  }
  ```
</CodeGroup>

## Response

<ParamField type="int32">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="EndpointLog">
  Detailed log information for the endpoint execution.

  <Expandable>
    <ParamField type="uint64">
      Unique identifier for the endpoint log entry.
    </ParamField>

    <ParamField type="uint64">
      The identifier of the endpoint this log belongs to.
    </ParamField>

    <ParamField type="string">
      Source system or origin of the endpoint execution.
    </ParamField>

    <ParamField type="string">
      Current status of the endpoint execution.
    </ParamField>

    <ParamField type="uint64">
      Associated project identifier.
    </ParamField>

    <ParamField type="uint64">
      Associated organization identifier.
    </ParamField>

    <ParamField type="uint64">
      Model identifier tied to the endpoint provider.
    </ParamField>

    <ParamField type="uint64">
      Time taken for the endpoint execution in milliseconds.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was created.
    </ParamField>

    <ParamField type="timestamp">
      Timestamp when the log entry was last updated.
    </ParamField>

    <ParamField type="Metric[]">
      Array of performance and execution metrics.

      <Expandable>
        <ParamField type="string">
          Name of the metric.
        </ParamField>

        <ParamField type="string">
          Value of the metric.
        </ParamField>

        <ParamField type="string">
          Description of what the metric measures.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Metadata[]">
      Array of metadata associated with the endpoint execution.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the metadata entry.
        </ParamField>

        <ParamField type="string">
          The metadata key name.
        </ParamField>

        <ParamField type="string">
          The metadata value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Argument[]">
      Array of arguments passed to the endpoint during execution.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the argument.
        </ParamField>

        <ParamField type="string">
          Name of the argument.
        </ParamField>

        <ParamField type="string">
          Value of the argument.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Metadata[]">
      Array of execution options used for the endpoint.

      <Expandable>
        <ParamField type="uint64">
          Unique identifier for the option entry.
        </ParamField>

        <ParamField type="string">
          The option key name.
        </ParamField>

        <ParamField type="string">
          The option value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Error information, if applicable.

  <Expandable>
    <ResponseField name="errorCode" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Detailed error message.
    </ResponseField>
  </Expandable>
</ParamField>


# Invoke
Source: https://doc.rapida.ai/api-reference/endpoint/invoke



Invokes an endpoint to execute a specific operation using the Rapida API.

<Info>
  For full setup and authentication options, see the Installation guide: [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField type="ConnectionConfig">
  Configuration for the client connection.
</ParamField>

<ParamField type="InvokeRequest">
  <Expandable>
    <ParamField type="EndpointDefinition">
      <Expandable>
        <ParamField type="number">
          Unique identifier of the endpoint to invoke.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Arguments passed to the endpoint as a key-value map.
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Request options for runtime behavior and configuration.
    </ParamField>

    <ParamField type="Map<string, google_protobuf_any_pb.Any>">
      Metadata associated with the request for tracking and analytics.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      EndpointDefinition,
      InvokeRequest,
      invoke,
      string_to_any,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )

  argument_value = string_to_any("Hello how are you doing")
  metadata_value = string_to_any("metadata_to_track")
  option_value = string_to_any("4567898656789")

  response = invoke(
      client_cfg=connection_config,
      request=InvokeRequest(
          endpoint=EndpointDefinition(endpointId=2223006263292198912),
          args={"can": argument_value},
          metadata={"test": metadata_value},
          options={"opts1": option_value},
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	"github.com/rapidaai/rapida-go/rapida/utils"
  	"google.golang.org/protobuf/types/known/anypb"
  )

  func main() {
  	// for more authentication check https://doc.rapida.ai/api-reference/authentication
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK("RAPIDA_PROJECT_CREDENTIAL"))
  	argumentValue, _ := utils.StringToAny("Hello how are you doing")
  	metadataValue, _ := utils.StringToAny("metadata_to_track")
  	optionValue, _ := utils.Int64ToAny(4567898656789)
  	response, _ := clients.Invoke(context.Background(), connectionConfig, &rapida_proto.InvokeRequest{
  		Endpoint: &rapida_proto.EndpointDefinition{
  			EndpointId: RAPIDA_ENDPOINT_ID,
  		},
  		Args: map[string]*anypb.Any{
  			"can": argumentValue,
  		},
  		Metadata: map[string]*anypb.Any{
  			"test": metadataValue,
  		},
  		Options: map[string]*anypb.Any{
  			"opts1": optionValue,
  		},
  	})

    for _, content:= range response.GetMetrics() {
      fmt.Println(string(content.Name), string(content.Value))
    }

    for _, content:= range response.GetData() {
      fmt.Println(string(content.GetContent()))
    }

  }
  ```

  ```typescript NodeJs  theme={null}
  import {
    Invoke,
    ConnectionConfig,
    GetEndpoint,
    InvokeRequest,
    EndpointDefinition,
    StringToAny,
    ToContentText
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    invokeEndpoint(connectionCfg)
  })();


  async function invokeEndpoint(connectionCfg) {
    const request = new InvokeRequest();
    let endpointDef = new EndpointDefinition();
    endpointDef.setEndpointid(RAPIDA_ENDPOINT_ID);
    endpointDef.setVersion("latest");
    request.setEndpoint(endpointDef);
    request.getArgsMap().set("can", StringToAny("Prompt_ARGUMENT"));
    request.getArgsMap().set("can", StringToAny("Prompt_ARGUMENT_2"));

    // metadata
    request.getMetadataMap().set("track", StringToAny("metadata_to_track"));

    // options
    request.getOptionsMap().set("model_options", StringToAny("x"));
    const response = await Invoke(connectionCfg, request);
    if (response.getError()) {
      console.error(
        "Error invoking endpoint:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("Endpoint invoked successfully:", ToContentText(response.getDataList()));
      response.getMetricsList().forEach(x => console.log(x.getName(), x.getValue()))
    }
  }
  ```
</CodeGroup>

### Response

<ParamField type="int">
  Numeric status code for the operation.
</ParamField>

<ParamField type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField type="Error">
  <Expandable>
    <ResponseField name="errorCode" type="string (uint64)">
      Stable, machine-readable numeric code for the error.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented error message for debugging.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      End-user-friendly error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="array" description="Array of Content, representing the returned results.">
  <Expandable>
    <ParamField type="string">
      Name of the content.
    </ParamField>

    <ParamField type="string">
      Type of the content (e.g., audio, image, video, text).
    </ParamField>

    <ParamField type="string">
      Format of the content (e.g., raw string, URL).
    </ParamField>

    <ParamField type="bytes">
      Raw content data.
    </ParamField>

    <ParamField type="object">
      Metadata of the content.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="uint64">
  Unique ID for tracking the request.
</ParamField>

<ParamField type="uint64">
  Duration of the operation in milliseconds.
</ParamField>

<ParamField type="array" description="Performance metrics captured during the request.">
  <Expandable>
    <ParamField type="string">
      Name of the metric.
    </ParamField>

    <ParamField type="string">
      Value of the metric.
    </ParamField>

    <ParamField type="string">
      Description of the metric.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object" description="Structured metadata related to the response." />


# Installation
Source: https://doc.rapida.ai/api-reference/installation

Build natural-sounding AI voice assistants with ease

The Rapida SDK lets you quickly integrate voice, chat, and AI-powered workflows into your applications. This guide covers installation and authentication for different languages. For detailed API references, see the [API Reference](/api-reference).

<Columns>
  <Card icon="audio-lines" title="Node.js Voice Agent" href="https://github.com/rapidaai/rapida-nodejs-recipes">
    A web voice AI assistant built with Node.js.
  </Card>

  <Card icon="audio-lines" title="Python Voice Agent" href="https://github.com/rapidaai/rapida-python-recipes">
    A voice AI assistant built with Python.
  </Card>

  <Card icon="audio-lines" title="Go Voice Agent" href="https://github.com/rapidaai/rapida-go-recipes">
    A voice AI assistant built with Go.
  </Card>

  <Card icon="audio-lines" title="React Voice Agent" href="https://github.com/rapidaai/rapida-react-recipes">
    A voice AI assistant built with React.
  </Card>
</Columns>

## Prerequisites

<Info>
  **Node.js and React**: Please install [Node.js](https://nodejs.org/en)
  (version 16.0.0 or higher) before proceeding.
</Info>

<Info>
  **Go**: Please install [Go](https://golang.org/dl/) (version 1.21 or higher)
  before proceeding.
</Info>

<Info>
  **Python**: Please install [Python](https://python.org/downloads/) (version
  3.9 or higher) before proceeding.
</Info>

You can check your installed versions:

<CodeGroup>
  ```bash Node.js theme={null}
  node --version
  ```

  ```bash Go theme={null}
  go version
  ```

  ```bash Python theme={null}
  python --version
  ```
</CodeGroup>

## Installation

<CodeGroup>
  ```bash React theme={null}
  # React (choose one)
  npm install @rapidaai/react      # npm
  yarn add @rapidaai/react         # yarn
  pnpm add @rapidaai/react         # pnpm
  ```

  ```bash Node.js theme={null}
  # Node.js (choose one)
  npm install @rapidaai/nodejs     # npm
  yarn add @rapidaai/nodejs        # yarn
  pnpm add @rapidaai/nodejs        # pnpm
  ```

  ```bash Go theme={null}
  # Go
  go get github.com/rapidaai/rapida-go@latest
  ```

  ```bash Python theme={null}
  # Python (choose one)
  pip install rapida-python        # pip
  pip3 install rapida-python       # pip3
  # Other languages: see tabs
  ```
</CodeGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Module not found">
    This may be due to an incorrect package name or version.

    **Solution**:

    1. Verify you're using the correct package name for your platform
    2. Check that you have the minimum required version of Node.js, Go, or Python
    3. Try reinstalling the package
  </Accordion>

  <Accordion title="Authentication errors">
    This usually indicates invalid or missing credentials.

    **Solution**:

    1. Verify your API keys are correct in your `.env` file
    2. Check that your environment variables are being loaded properly
    3. Ensure you're using the right authentication method (Personal Token vs SDK API Key)
  </Accordion>

  <Accordion title="Go module issues">
    If you encounter Go module or dependency issues.

    **Solution**:

    1. Ensure Go modules are enabled: `go mod init your-project-name`
    2. Run `go mod tidy` to clean up dependencies
    3. Check that you're using Go 1.21 or higher
  </Accordion>

  <Accordion title="Node.js version compatibility">
    If you encounter issues with Node.js compatibility.

    **Solution**:

    1. Upgrade to Node.js 16.0.0 or higher
    2. Clear your npm cache: `npm cache clean --force`
    3. Remove `node_modules` and reinstall: `rm -rf node_modules && npm install`
  </Accordion>
</AccordionGroup>

## Next Steps

* Explore the [API Reference](/api-reference) for all available endpoints
* Learn how to configure [Assistants](/assistants/overview) and build custom experiences
* Read the [Authentication](/api-reference/authentication) guide to set up API access
* Review [API Reference](/api-reference/authentication) for all available endpoints


# create-api-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/create-api-deployment

/openapi/talk-api.yaml post /v1/assistant-deployment/create-api-deployment
Creates an API deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# create-debugger-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/create-debugger-deployment

/openapi/talk-api.yaml post /v1/assistant-deployment/create-debugger-deployment
Creates a debugger deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# create-phone-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/create-phone-deployment

/openapi/talk-api.yaml post /v1/assistant-deployment/create-phone-deployment
Creates a phone deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# create-webplugin-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/create-webplugin-deployment

/openapi/talk-api.yaml post /v1/assistant-deployment/create-webplugin-deployment
Creates a web plugin deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# create-whatsapp-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/create-whatsapp-deployment

/openapi/talk-api.yaml post /v1/assistant-deployment/create-whatsapp-deployment
Creates a WhatsApp deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# get-all-api-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-all-api-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-all-api-deployment/{assistantId}
Gets API deployments for an assistant. This endpoint requires user authentication with organization and project scope.



# get-all-debugger-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-all-debugger-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-all-debugger-deployment/{assistantId}
Gets debugger deployments for an assistant. This endpoint requires user authentication with organization and project scope.



# get-all-phone-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-all-phone-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-all-phone-deployment/{assistantId}
Gets phone deployments for an assistant. This endpoint requires user authentication with organization and project scope.



# get-all-webplugin-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-all-webplugin-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-all-webplugin-deployment/{assistantId}
Gets web plugin deployments for an assistant. This endpoint requires user authentication with organization and project scope.



# get-all-whatsapp-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-all-whatsapp-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-all-whatsapp-deployment/{assistantId}
Gets WhatsApp deployments for an assistant. This endpoint requires user authentication with organization and project scope.



# get-api-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-api-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-api-deployment/{assistantId}
Gets the latest API deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# get-debugger-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-debugger-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-debugger-deployment/{assistantId}
Gets the latest debugger deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# get-phone-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-phone-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-phone-deployment/{assistantId}
Gets the latest phone deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# get-webplugin-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-webplugin-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-webplugin-deployment/{assistantId}
Gets the latest web plugin deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# get-whatsapp-deployment
Source: https://doc.rapida.ai/api-reference/rest/assistant-deployments/get-whatsapp-deployment

/openapi/talk-api.yaml get /v1/assistant-deployment/get-whatsapp-deployment/{assistantId}
Gets the latest WhatsApp deployment for an assistant. This endpoint requires user authentication with organization and project scope.



# create-assistant
Source: https://doc.rapida.ai/api-reference/rest/assistants/create-assistant

/openapi/talk-api.yaml post /v1/assistant/create-assistant
Creates an assistant with one provider configuration and optional tools, knowledge, and tags.



# Authentication
Source: https://doc.rapida.ai/api-reference/rest/authentication

Authenticate REST API requests with an API key.

The REST API accepts an API key in the `x-api-key` header, the `x-api-key` query parameter, or the `Authentication` header. Create and rotate API keys from your Rapida project credentials.

<CodeGroup>
  ```bash x-api-key header theme={null}
  curl --request POST "https://assistant-01.in.rapida.ai/v1/talk/create-phone-call" \
    --header "Content-Type: application/json" \
    --header "x-api-key: $RAPIDA_API_KEY" \
    --data '{
      "assistant": {
        "assistantId": "2227823180112723968",
        "version": "latest"
      },
      "toNumber": "+14155550123"
    }'
  ```

  ```bash x-api-key query parameter theme={null}
  curl --request POST "https://assistant-01.in.rapida.ai/v1/talk/create-phone-call?x-api-key=$RAPIDA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "assistant": {
        "assistantId": "2227823180112723968",
        "version": "latest"
      },
      "toNumber": "+14155550123"
    }'
  ```

  ```bash Authentication header theme={null}
  curl --request POST "https://assistant-01.in.rapida.ai/v1/talk/create-phone-call" \
    --header "Content-Type: application/json" \
    --header "Authentication: $RAPIDA_API_KEY" \
    --data '{
      "assistant": {
        "assistantId": "2227823180112723968",
        "version": "latest"
      },
      "toNumber": "+14155550123"
    }'
  ```
</CodeGroup>

## Authentication parameters

<ParamField type="string">
  API key sent as a request header.
</ParamField>

<ParamField type="string">
  API key sent as a query parameter.
</ParamField>

<ParamField type="string">
  API key sent as an `Authentication` header.
</ParamField>

Use one authentication method per request. Prefer headers for server-side integrations because query parameters can appear in logs.

## Optional headers

<ParamField type="string">
  Optional user identifier to propagate with the request.
</ParamField>

<ParamField type="string">
  Optional client source identifier. SDK clients send this automatically.
</ParamField>

## Base URLs

Use the endpoint for the region where your assistant API is hosted.

```text theme={null}
https://assistant-01.in.rapida.ai
https://assistant-01.us.rapida.ai
```

<Warning>
  Do not expose project API keys in browser or mobile clients. Send REST API requests from a trusted backend service.
</Warning>


# create-bulk-phone-call
Source: https://doc.rapida.ai/api-reference/rest/calls/create-bulk-phone-call

/openapi/talk-api.yaml post /v1/talk/create-bulk-phone-call
Starts multiple outbound phone calls using configured assistants and returns the created conversation identifiers.



# create-phone-call
Source: https://doc.rapida.ai/api-reference/rest/calls/create-phone-call

/openapi/talk-api.yaml post /v1/talk/create-phone-call
Starts one outbound phone call using the configured assistant and returns the created conversation identifier.



# AgentKit — Custom LLM Backend
Source: https://doc.rapida.ai/assistants/agentkit

Create an AgentKit assistant in Rapida, connect your own gRPC backend, and go live quickly with production-safe patterns.

AgentKit lets you run your own backend for live voice conversations.

Rapida handles telephony + STT + TTS, while your server handles reasoning and tool execution over a bidirectional gRPC stream.

With AgentKit, you can connect any LLM backend with Rapida over gRPC.

***

## Quickstart

<Steps>
  <Step title="Create an AgentKit assistant in Rapida">
    <img alt="AgentKit assistant configuration in Rapida" />

    <img alt="AgentKit assistant configuration in Rapida" />

    1. Open your Rapida dashboard and create (or edit) an assistant.
    2. In provider/model settings, choose **AgentKit** as the LLM backend.
    3. Configure the AgentKit connection:
       * **AgentKit endpoint**: your gRPC server address, such as `agent.your-domain.com:50051`
       * **Metadata**: gRPC metadata sent on the `Talk` stream, such as `authorization` or tenant routing keys
       * **Connection tuning**: connect timeout, keepalive, and max message sizes
       * **Security**: transport security, TLS verification, TLS server name, and optional CA certificate
    4. Save the assistant version and release it.
    5. Attach your voice deployment channel (phone/web/etc.) to this version.

    <Info>
      Your AgentKit endpoint must be reachable from the Rapida network and should be provided as `host:port`, without `http://`, `https://`, or `grpc://`. Localhost works only for local development setups where connectivity is bridged.
    </Info>
  </Step>

  <Step title="Start from official examples">
    Use the Python or Node.js starter depending on your backend stack.

    <CodeGroup>
      ```bash Python theme={null}
      git clone https://github.com/rapidaai/rapida-python-recipes.git
      cd rapida-python-recipes
      pip install -r requirements.txt

      cd examples/python/agentkit
      export OPENAI_API_KEY="<your_key>"
      python main.py --host 0.0.0.0 --port 50051
      ```

      ```bash Node.js theme={null}
      git clone https://github.com/rapidaai/rapida-nodejs-recipes.git
      cd rapida-nodejs-recipes
      npm install

      export AGENTKIT_PORT=50051
      # Optional. Enables token auth on gRPC metadata key: authorization
      export AGENTKIT_TOKEN="<shared-token>"
      node agentkit/index.js
      ```
    </CodeGroup>

    Node.js reference implementation: `agentkit/index.js`.
  </Step>

  <Step title="Implement required stream flow">
    Implement `Talk(...)` using the lifecycle contract described in **Stream Lifecycle** below.

    Minimum required order:

    1. handle `initialization` first and acknowledge it
    2. handle optional `configuration` updates
    3. process `message` turns and stream assistant/tool outputs

    ```python theme={null}
    def Talk(self, request_iterator, context):
        for request in request_iterator:
            if self.is_initialization_request(request):
                yield self.initialization_response(request.initialization)

            elif self.is_configuration_request(request):
                yield self.configuration_response(request.configuration)

            elif self.is_message_request(request):
                if not self.is_text_message(request):
                    yield self.error_response(501, "Audio not implemented")
                    continue

                msg_id = self.get_message_id(request)
                yield self.assistant_response(msg_id, "Working on it... ", completed=False)
                yield self.assistant_response(msg_id, "Done.", completed=True)

            else:
                yield self.error_response(400, "Unknown request type")
    ```

    <Warning>
      If `initialization` is not handled first, conversations can fail with request-shape errors.
    </Warning>

    Node.js servers implement the same flow by extending `AgentKitAgent` and writing responses to the gRPC stream:

    ```js theme={null}
    import { AgentKitAgent, AgentKitServer } from "@rapidaai/nodejs";

    class EchoAgent extends AgentKitAgent {
      talk(call) {
        call.on("data", (request) => {
          if (this.isInitializationRequest(request)) {
            call.write(this.initializationResponse(request.getInitialization()));
            return;
          }

          if (this.isConfigurationRequest(request)) {
            call.write(this.configurationResponse(request.getConfiguration()));
            return;
          }

          if (this.isTextMessage(request)) {
            const messageId = this.getMessageId(request);
            const text = this.getUserText(request);

            call.write(this.assistantResponse(messageId, `You said: ${text}`, false));
            call.write(
              this.assistantResponse(
                messageId,
                "Thanks, I received your message.",
                true
              )
            );
          }
        });

        call.on("end", () => call.end());
      }
    }

    const server = new AgentKitServer({
      agent: new EchoAgent(),
      port: Number(process.env.AGENTKIT_PORT || 50051),
    });

    await server.start();
    ```
  </Step>

  <Step title="Implement tool lifecycle">
    For each tool execution in your backend:

    1. emit `tool_call(...)`
    2. execute tool locally
    3. emit `tool_call_result(...)`
    4. continue assistant response (or send call directive)

    ```python theme={null}
    import uuid

    tool_id = str(uuid.uuid4())

    yield self.tool_call(msg_id, tool_id, "get_weather", {"city": "London"})
    result = {"city": "London", "temp_c": 22}
    yield self.tool_call_result(msg_id, tool_id, "get_weather", result, success=True)
    yield self.assistant_response(msg_id, "In London it's 22°C.", completed=True)
    ```

    For call-ending directives (`END_CONVERSATION` / `TRANSFER_CONVERSATION`), include `toolId` and `name` in the directive payload.
  </Step>

  <Step title="Configure security">
    Token auth:

    ```python theme={null}
    server = AgentKitServer(
        agent=MyAgent(),
        host="0.0.0.0",
        port=50051,
        auth_config={"enabled": True, "token": os.getenv("AGENTKIT_TOKEN")},
    )
    ```

    In Rapida, add the same token as AgentKit metadata. For example, set metadata key `authorization` to the shared token if your server checks the gRPC `authorization` metadata key.

    TLS:

    ```python theme={null}
    server = AgentKitServer(
        agent=MyAgent(),
        host="0.0.0.0",
        port=50051,
        ssl_config={
            "cert_path": "/etc/ssl/server.crt",
            "key_path": "/etc/ssl/server.key",
        },
    )
    ```
  </Step>

  <Step title="Validate before customer traffic">
    Use the test client:

    ```bash theme={null}
    python examples/python/executor/agentkit/test_client.py localhost:50051
    ```

    Validate:

    * initialization acknowledgement
    * assistant chunks and final response
    * tool call and tool call result events (for tooling flows)
  </Step>
</Steps>

***

## AgentKit configuration options

AgentKit versions store both the backend address and the gRPC connection policy. Use the same fields when you create a new AgentKit assistant or create a new AgentKit version for an existing assistant.

| Setting                  | API field             | Default       | Allowed values or range     | When to change it                                                           |
| ------------------------ | --------------------- | ------------- | --------------------------- | --------------------------------------------------------------------------- |
| AgentKit endpoint        | `agentKitUrl`         | Required      | `host` or `host:port`       | Set this to the reachable gRPC endpoint for your backend.                   |
| Metadata                 | `metadata`            | `{}`          | String key/value map        | Pass auth tokens, tenant IDs, or routing headers as gRPC metadata.          |
| Transport security       | `transportSecurity`   | `TLS`         | `TLS`, `PLAINTEXT`          | Use `PLAINTEXT` only for trusted private networks or local testing.         |
| TLS verification         | `tlsVerification`     | `VERIFY`      | `VERIFY`, `SKIP_VERIFY`     | Use `SKIP_VERIFY` only while diagnosing certificate issues.                 |
| TLS server name          | `tlsServerName`       | Endpoint host | DNS name                    | Set this when the certificate SAN does not match the dial address.          |
| TLS certificate          | `certificate`         | Empty         | PEM CA certificate          | Add a CA certificate for private or self-signed TLS.                        |
| Connect timeout          | `connectTimeoutMs`    | `10000`       | `1` to `300000` ms          | Raise this for slow private links; lower it to fail over faster.            |
| Keepalive time           | `keepaliveTimeMs`     | `30000`       | `10000` to `3600000` ms     | Controls how often the client sends keepalive pings.                        |
| Keepalive timeout        | `keepaliveTimeoutMs`  | `10000`       | `1000` to `300000` ms       | Controls how long Rapida waits for a keepalive response.                    |
| Max receive message size | `maxRecvMessageBytes` | `16777216`    | `1024` to `104857600` bytes | Increase for large tool results or custom payloads.                         |
| Max send message size    | `maxSendMessageBytes` | `16777216`    | `1024` to `104857600` bytes | Increase if your backend receives large initialization or message payloads. |

<Warning>
  Do not use `SKIP_VERIFY` or `PLAINTEXT` for production internet-facing traffic unless the connection is protected by another trusted network boundary.
</Warning>

### Runtime overrides

You can override AgentKit connection settings for a single outbound phone call by passing `agentkit.*` keys in `CreatePhoneCallRequest.options`. Runtime overrides apply only to the conversation being created.

```json theme={null}
{
  "options": {
    "agentkit.metadata": {
      "authorization": "shared-token",
      "tenant": "acme"
    },
    "agentkit.transportSecurity": "TLS",
    "agentkit.tlsVerification": "VERIFY",
    "agentkit.tlsServerName": "agent.your-domain.com",
    "agentkit.connectTimeoutMs": 10000,
    "agentkit.keepaliveTimeMs": 30000,
    "agentkit.keepaliveTimeoutMs": 10000,
    "agentkit.maxRecvMessageBytes": 16777216,
    "agentkit.maxSendMessageBytes": 16777216
  }
}
```

| Option key                     | Type     | Overrides                                                                         |
| ------------------------------ | -------- | --------------------------------------------------------------------------------- |
| `agentkit.metadata`            | `object` | gRPC metadata sent to the AgentKit server. Values are merged with saved metadata. |
| `agentkit.transportSecurity`   | `string` | Transport security policy, such as `TLS` or `PLAINTEXT`.                          |
| `agentkit.tlsVerification`     | `string` | TLS verification policy, such as `VERIFY` or `SKIP_VERIFY`.                       |
| `agentkit.tlsServerName`       | `string` | TLS server name used for certificate verification.                                |
| `agentkit.certificate`         | `string` | PEM CA certificate.                                                               |
| `agentkit.connectTimeoutMs`    | `number` | Connect timeout in milliseconds.                                                  |
| `agentkit.keepaliveTimeMs`     | `number` | Keepalive ping interval in milliseconds.                                          |
| `agentkit.keepaliveTimeoutMs`  | `number` | Keepalive timeout in milliseconds.                                                |
| `agentkit.maxRecvMessageBytes` | `number` | Maximum inbound message size.                                                     |
| `agentkit.maxSendMessageBytes` | `number` | Maximum outbound message size.                                                    |

<Note>
  `agentkit.*` keys configure Rapida's connection to your AgentKit server. They are not forwarded in the AgentKit initialization payload. Other call options remain available to your backend through the initialization `options` map.
</Note>

### API shape

Use `agentkit` inside `CreateAssistantProviderRequest` for both initial assistant creation and new AgentKit versions.

```json theme={null}
{
  "assistantId": "2227823180112723968",
  "description": "Move AgentKit to the production backend",
  "agentkit": {
    "agentKitUrl": "agent.your-domain.com:50051",
    "metadata": {
      "authorization": "shared-token",
      "tenant": "acme"
    },
    "transportSecurity": "TLS",
    "tlsVerification": "VERIFY",
    "tlsServerName": "agent.your-domain.com",
    "connectTimeoutMs": 10000,
    "keepaliveTimeMs": 30000,
    "keepaliveTimeoutMs": 10000,
    "maxRecvMessageBytes": 16777216,
    "maxSendMessageBytes": 16777216,
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  }
}
```

See [Create assistant provider](/api-reference/assistant/create-assistant-provider) for SDK examples.

***

## Stream Lifecycle

The AgentKit stream is long-lived and stateful. Treat it as a lifecycle, not as isolated RPC requests.

### Lifecycle phases

| Phase             | Inbound frame from Rapida          | Outbound frame from your backend              | Required       | Purpose                                              |
| ----------------- | ---------------------------------- | --------------------------------------------- | -------------- | ---------------------------------------------------- |
| 1. Handshake      | `initialization`                   | `initialization_response(...)`                | Yes            | Establish conversation identity and runtime context. |
| 2. Runtime config | `configuration`                    | `configuration_response(...)`                 | Optional       | Apply stream-mode/runtime updates.                   |
| 3. User turn      | `message`                          | `assistant_response(...)` chunks + final      | Yes (per turn) | Return assistant output for each user turn.          |
| 4. Tool execution | Internal tool decision during turn | `tool_call(...)` then `tool_call_result(...)` | Optional       | Report tool lifecycle and results.                   |
| 5. Call directive | Internal decision to transfer/end  | `toolCall` with action + `toolId` + `name`    | Optional       | Signal call transfer or termination.                 |
| 6. Termination    | Client/server closes stream        | none (or final error/event)                   | Yes            | End stream cleanly and release resources.            |

### Turn-level sequence (recommended)

1. Receive `message` and extract `msg_id` + text.
2. Emit one or more `assistant_response(..., completed=False)` chunks.
3. If tool is needed:
   * emit `tool_call(msg_id, tool_id, name, args)`
   * execute tool
   * emit `tool_call_result(msg_id, tool_id, name, result, success=...)`
4. Emit final `assistant_response(..., completed=True)` for that turn.
5. Repeat for next `message` frame until stream closes.

### State and correlation rules

* `initialization` is always first and must be acknowledged.
* `assistant.id`, `toolCall.id`, and `toolCallResult.id` should match the current `message.id`.
* `tool_id` must be stable between `tool_call` and `tool_call_result`.
* Final assistant frame per user turn must set `completed=True`.
* For call-ending/transfer directives, include `toolId` and `name` for correlation.

***

## Request Types (`TalkInput`)

| Request Type     | What it is                                                                                 | Why it exists                                                     | What your backend should do                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `initialization` | First frame of every stream (`assistantConversationId`, assistant metadata, runtime args). | Establishes conversation/session context before user turns start. | Always acknowledge using `initialization_response(request.initialization)`.                                  |
| `configuration`  | Optional runtime configuration update frame.                                               | Allows stream behavior updates mid-session.                       | Acknowledge with `configuration_response(request.configuration)`.                                            |
| `message`        | User turn payload (`id`, `text`/`audio`, `completed`, `time`).                             | Carries the actual user input to process.                         | Parse with helpers (`is_text_message`, `get_user_text`, `get_message_id`) and emit assistant/tool responses. |

***

## Response Types (`TalkOutput`)

| Response Type      | What it is                                                                    | Why it exists                                             | When to emit                                              |
| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `code` / `success` | Base response envelope fields.                                                | Standard status signaling for each frame.                 | On every response (`200/true` by default).                |
| `initialization`   | Initialization acknowledgement payload.                                       | Confirms handshake accepted.                              | Via `initialization_response(...)`.                       |
| `assistant`        | Assistant chunk/final text (`id`, `text`, `completed`).                       | Streams voice response content back to Rapida.            | Via `assistant_response(...)` for chunks and final frame. |
| `toolCall`         | Tool lifecycle or directive event (`id`, `toolId`, `name`, `action`, `args`). | Announces tool start or call-level action (transfer/end). | Via `tool_call(...)` or explicit directive payload.       |
| `toolCallResult`   | Tool execution result (`id`, `toolId`, `name`, `result`).                     | Closes the tool lifecycle and reports output.             | Via `tool_call_result(...)` after tool execution.         |
| `interruption`     | Optional interruption signal.                                                 | Represents interruption events in stream.                 | When interruption handling is implemented.                |
| `error`            | Error frame (`errorCode`, `errorMessage`).                                    | Signals unrecoverable backend failures.                   | Via `error_response(code, message)`.                      |

<Note>
  Keep the same `tool_id` between `tool_call` and `tool_call_result`. For call-ending directives, include `toolId` and `name` for correlation.
</Note>

***

## Utilities

### Response Builder Utilities (`AgentKitAgent`)

| Utility                                                         | Input                               | What it returns                 | Why/When to use                        |
| --------------------------------------------------------------- | ----------------------------------- | ------------------------------- | -------------------------------------- |
| `response(code=200, success=True, **kwargs)`                    | Base status + payload fields        | `TalkOutput`                    | Low-level custom frame builder.        |
| `initialization_response(initialization)`                       | `ConversationInitialization`        | `TalkOutput.initialization`     | Required ack for first frame.          |
| `configuration_response(configuration)`                         | `ConversationConfiguration`         | `TalkOutput` ack                | Optional config ack frame.             |
| `assistant_response(msg_id, content, completed=False)`          | message id + text + completion flag | `TalkOutput.assistant`          | Streaming/final assistant text frames. |
| `error_response(code, message)`                                 | code + message                      | `TalkOutput.error`              | Error signaling in stream.             |
| `tool_call(msg_id, tool_id, name, args)`                        | tool start metadata                 | `TalkOutput.toolCall`           | Start tool lifecycle event.            |
| `tool_call_result(msg_id, tool_id, name, result, success=True)` | tool result metadata                | `TalkOutput.toolCallResult`     | Finish tool lifecycle event.           |
| `transfer_call(msg_id, args)`                                   | transfer args                       | `TalkOutput.toolCall` directive | Transfer call action.                  |
| `terminate_call(msg_id, args)`                                  | termination args                    | `TalkOutput.toolCall` directive | End-conversation action.               |

### Request Helper Utilities (`AgentKitAgent`)

| Utility                              | What it checks/returns         | Why/When to use                       |
| ------------------------------------ | ------------------------------ | ------------------------------------- |
| `is_initialization_request(request)` | `True` if initialization frame | First branch in `Talk`.               |
| `is_configuration_request(request)`  | `True` if configuration frame  | Handle optional config updates.       |
| `is_message_request(request)`        | `True` if message frame        | Main user-turn branch.                |
| `is_text_message(request)`           | `True` for text turn           | Process user text safely.             |
| `is_audio_message(request)`          | `True` for audio turn          | Handle/decline audio mode explicitly. |
| `get_user_text(request)`             | User text or `None`            | Extract text payload.                 |
| `get_message_id(request)`            | Message id or `None`           | Correlate assistant/tool frames.      |
| `get_conversation_id(request)`       | Conversation id or `None`      | Conversation-scoped state mapping.    |
| `get_assistant_id(request)`          | Assistant id or `None`         | Logging/routing/debug context.        |

***

## Local Development Setup (ngrok)

For local development, expose your AgentKit server to Rapida with ngrok:

```bash theme={null}
ngrok tcp 50051
```

ngrok prints a forwarding endpoint like:

* `tcp://0.tcp.ngrok.io:12345`

Use the host and port (`0.tcp.ngrok.io:12345`) as the AgentKit URL in your Rapida assistant configuration.

Development notes:

* keep the local AgentKit server running on port `50051` during testing
* if auth is enabled, set the same token in Rapida AgentKit provider config
* if ngrok restarts, the endpoint changes unless a reserved domain is configured

***

## Example Matrix (GitHub)

Python base path:

* `https://github.com/rapidaai/rapida-python-recipes/tree/main`

Node.js base path:

* `https://github.com/rapidaai/rapida-nodejs-recipes/tree/main`

| Example                                        | Purpose                                    | GitHub                                                                                                           |
| ---------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `agentkit/index.js`                            | Node.js EchoAgent gRPC server baseline     | [Open](https://github.com/rapidaai/rapida-nodejs-recipes/blob/main/agentkit/index.js)                            |
| `agentkit/main.py`                             | Minimal production-style AgentKit baseline | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/agentkit/main.py)                             |
| `executor/agentkit/openai-gpt.py`              | OpenAI chat + tool lifecycle               | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/openai-gpt.py)              |
| `executor/agentkit/azure-openai-gpt.py`        | Azure OpenAI + tool lifecycle              | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/azure-openai-gpt.py)        |
| `executor/agentkit/anthropic-claude.py`        | Anthropic Claude + tool lifecycle          | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/anthropic-claude.py)        |
| `executor/agentkit/gemini-example.py`          | Google Gemini + function/tool flow         | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/gemini-example.py)          |
| `executor/agentkit/langchain-agent.py`         | LangChain orchestrated backend             | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/langchain-agent.py)         |
| `executor/agentkit/crewai-multi-agent.py`      | CrewAI multi-agent orchestration           | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/crewai-multi-agent.py)      |
| `executor/agentkit/autogen-collaborative.py`   | AutoGen collaborative agents               | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/autogen-collaborative.py)   |
| `executor/agentkit/n8n-workflow.py`            | n8n workflow automation integration        | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/n8n-workflow.py)            |
| `executor/agentkit/example-with-ssl-option.py` | TLS/auth focused server setup              | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/example-with-ssl-option.py) |
| `executor/agentkit/test_client.py`             | Local stream validation client             | [Open](https://github.com/rapidaai/rapida-python-recipes/blob/main/executor/agentkit/test_client.py)             |

***

## Production Checklist

* handle `initialization` first on every stream
* always send final `assistant_response(..., completed=True)`
* keep `tool_id` consistent between `tool_call` and `tool_call_result`
* include `toolId` + `name` for call-ending directives
* do not hardcode secrets in source code
* configure TLS + auth for production
* review [AgentKit scaling](/assistants/agentkit/scaling) before production traffic

***

## Related

* [Create Assistant](/assistants/create-assistant)
* [Scale AgentKit backends](/assistants/agentkit/scaling)
* [Tools Overview](/assistants/introduction-to-tools)
* [Python SDK Installation](/api-reference/installation)


# Scale AgentKit backends
Source: https://doc.rapida.ai/assistants/agentkit/scaling

Benchmark, horizontally scale, route, and operate customer-owned AgentKit gRPC backends.

AgentKit backends scale like long-lived gRPC services. Rapida opens one `Talk` stream for each live conversation and keeps that stream attached to one backend replica until the conversation ends.

Use a stable load-balanced endpoint as your AgentKit URL, such as `agent.your-domain.com:50051`. Scale the backend replicas behind that endpoint.

<Info>
  Active conversations are distributed when new streams are created. An active stream is not moved between replicas during the conversation.
</Info>

## Capacity benchmark per instance

There is no universal conversations-per-pod number. Capacity depends on your runtime, LLM latency, tool latency, memory use, streaming behavior, and how much state you keep in the process.

Benchmark each AgentKit backend shape before setting production autoscaling limits.

Track these metrics during a load test:

| Metric                       |     Target to record | Why it matters                                                 |
| ---------------------------- | -------------------: | -------------------------------------------------------------- |
| Active conversations per pod | Maximum stable value | Primary scaling unit for AgentKit.                             |
| Agent response latency       |        p50, p95, p99 | Confirms the agent can respond within voice latency targets.   |
| Stream setup latency         |             p50, p95 | Shows whether new calls can attach quickly.                    |
| Stream disconnect/error rate |           Percentage | Detects overload, network drops, and backend crashes.          |
| CPU and memory               |      p95 utilization | Defines safe pod requests, limits, and autoscaling thresholds. |
| External dependency latency  | p95 by provider/tool | LLMs and tools are often the real bottleneck.                  |

Use the highest stable conversation count that keeps latency and error rate inside your SLO, then add headroom.

```text theme={null}
required_pods = ceil(target_concurrent_conversations / safe_conversations_per_pod * headroom_factor)
```

Example:

```text theme={null}
target_concurrent_conversations = 2000
safe_conversations_per_pod = 250
headroom_factor = 1.4

required_pods = ceil(2000 / 250 * 1.4) = 12
```

Use the example only as a sizing pattern. Replace `safe_conversations_per_pod` with your measured benchmark.

### Text-only EC2 benchmark

Use this benchmark only for a text-only AgentKit backend.

In this benchmark:

* One active conversation means one open AgentKit `Talk` stream.
* Rapida handles telephony, audio, STT, and TTS.
* Your AgentKit backend receives text and returns text.
* The benchmark backend does not call an LLM, database, workflow engine, or external tool.
* Each message is small, usually under `4 KB`.
* Each active conversation sends one user message every `10` to `15` seconds.
* A passing test keeps CPU under `60%`, memory under `70%`, and stream errors under `0.1%`.

<Info>
  The numbers below are safe starting targets for capacity planning. They are not hard limits. Measure your own backend before using these numbers for a production commitment.
</Info>

### SDK concurrency knobs

AgentKit SDKs expose concurrency differently.

| SDK     | Concurrency knob                      | How to scale                                                                                            |
| ------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Python  | `AgentKitServer(..., max_workers=10)` | Increase `max_workers` for the synchronous starter, then scale with more processes, pods, or instances. |
| Node.js | No `max_workers` option               | Scale with more Node.js processes, pods, or instances behind the load balancer.                         |

Use `max_workers` guidance only for the Python SDK. For Node.js, use process and pod counts as the concurrency unit.

If you use Node.js, Go, or async Python, start with these targets:

| EC2 instance  | Safe active text conversations | Approx. user messages/sec | Use this when                                       |
| ------------- | -----------------------------: | ------------------------: | --------------------------------------------------- |
| `c7i.large`   |                        `2,000` |                     `150` | Small production shard.                             |
| `c7i.xlarge`  |                        `5,000` |                     `300` | Standard production shard.                          |
| `c7i.2xlarge` |                       `10,000` |                     `700` | Higher-density production shard.                    |
| `c7i.4xlarge` |                       `20,000` |                   `1,200` | Large production shard with tuned file descriptors. |
| `m7i.large`   |                        `3,000` |                     `150` | Text streams with more memory per conversation.     |
| `m7i.xlarge`  |                        `7,000` |                     `300` | Balanced CPU and memory.                            |
| `m7i.2xlarge` |                       `14,000` |                     `700` | Memory-heavy text context.                          |
| `m7i.4xlarge` |                       `28,000` |                   `1,200` | Large memory-heavy shard.                           |

Read the table like this:

```text theme={null}
If you need 20,000 active text conversations:

Option A: 10 x c7i.large instances at 2,000 conversations each
Option B: 4 x c7i.xlarge instances at 5,000 conversations each
Option C: 2 x c7i.2xlarge instances at 10,000 conversations each
Option D: 1 x c7i.4xlarge instance at 20,000 conversations each
```

For high availability, use at least two instances even when one larger instance can handle the expected load.

If you use the synchronous Python starter, size by `max_workers`. Each open stream can occupy a worker thread, so the safe active conversation count is close to the worker count.

| EC2 instance size | Suggested `max_workers` | Safe active text conversations |
| ----------------- | ----------------------: | -----------------------------: |
| 2 vCPU            |           `100` - `250` |                  `100` - `250` |
| 4 vCPU            |           `250` - `600` |                  `250` - `600` |
| 8 vCPU            |         `600` - `1,200` |                `600` - `1,200` |
| 16 vCPU           |       `1,200` - `2,500` |              `1,200` - `2,500` |

Use this process to find your real number:

1. Start at the target in the table.
2. Keep all streams open for at least `30` minutes.
3. Send one user message per conversation every `10` to `15` seconds.
4. Increase active conversations by `25%`.
5. Stop when CPU exceeds `60%`, memory exceeds `70%`, p95 response latency increases sharply, or stream errors exceed `0.1%`.
6. Use the last passing value as your measured capacity.
7. Plan production at `70%` of measured capacity so you have headroom.

Before testing above `10,000` active streams on one host:

* raise `ulimit -n` for the AgentKit process
* confirm proxy and server HTTP/2 max stream settings
* tune keepalive and idle timeouts across the load balancer, proxy, and server
* use connection draining before deploys
* track per-stream memory with production logging enabled

## Horizontal scaling

Run multiple AgentKit backend replicas behind one gRPC-aware load balancer.

Recommended production shape:

* Run AgentKit on Kubernetes, ECS, Nomad, or another orchestrator that supports health checks and rolling deploys.
* Put a gRPC-capable load balancer or service mesh in front of the replicas.
* Configure the Rapida AgentKit endpoint to the load-balanced address.
* Keep per-conversation state either stream-local or in an external store such as Redis or Postgres.
* Drain replicas before deployment so existing streams can finish.

For Python AgentKit servers, tune `max_workers` based on your benchmark and blocking behavior:

```python theme={null}
server = AgentKitServer(
    agent=MyAgent(),
    host="0.0.0.0",
    port=50051,
    max_workers=50,
)
```

For Node.js AgentKit servers, there is no `max_workers` setting. Run more Node.js processes, pods, or instances when you need more concurrency. Expose health checks for Kubernetes or the load balancer:

```js theme={null}
const server = new AgentKitServer({
  agent: new EchoAgent(),
  port: Number(process.env.AGENTKIT_PORT || 50051),
  httpHealthCheck: {
    host: "0.0.0.0",
    port: 8080,
    path: "/healthz",
  },
});
```

Scale on a mix of signals:

| Signal                         | Use                                                  |
| ------------------------------ | ---------------------------------------------------- |
| Active streams per pod         | Primary AgentKit-specific scaling signal.            |
| CPU and memory                 | Baseline infrastructure protection.                  |
| p95 response latency           | Detects saturation before hard failures.             |
| Queue depth or tool backlog    | Useful when the agent delegates work asynchronously. |
| LLM/provider rate-limit errors | Prevents scaling pods beyond downstream capacity.    |

## Traffic distribution by tenant or dynamic value

You can route AgentKit traffic dynamically with metadata and a gRPC-aware L7 proxy.

Rapida sends saved AgentKit metadata on the `Talk` stream. For outbound calls, you can override or add metadata for one conversation with `agentkit.metadata`.

```json theme={null}
{
  "options": {
    "agentkit.metadata": {
      "authorization": "shared-token",
      "tenant": "acme",
      "region": "us-east",
      "tier": "premium"
    }
  }
}
```

Distribution model:

1. Rapida dials one stable AgentKit endpoint.
2. The gRPC proxy inspects request metadata.
3. The proxy routes the new `Talk` stream to the matching backend pool.
4. The stream stays on that backend replica until the conversation ends.

Use this for:

* tenant-specific backend pools
* regional routing
* premium or regulated customer isolation
* model-tier routing
* canary releases by tenant or percentage

<Warning>
  A TCP/L4 load balancer cannot inspect AgentKit metadata. Use an L7 gRPC proxy such as Envoy, Istio, Linkerd, Traefik, or NGINX with gRPC routing support when routing depends on metadata.
</Warning>

Keep metadata keys simple and lowercase, such as `tenant`, `region`, or `tier`. If metadata can be influenced by customer input, validate or sign it before using it for authorization or isolation.

### NGINX metadata routing

Use NGINX as an L7 gRPC proxy when you want one public AgentKit endpoint and multiple backend pools.

This example routes by the AgentKit metadata key `tenant`:

```nginx theme={null}
worker_processes auto;

events {
  worker_connections 65535;
}

http {
  resolver kube-dns.kube-system.svc.cluster.local valid=10s ipv6=off;

  # AgentKit gRPC metadata is received as HTTP/2 headers.
  # Metadata key "tenant" is available as $http_tenant.
  map $http_tenant $agentkit_backend {
    default "";
    acme    grpc://agentkit-acme.agentkit.svc.cluster.local:50051;
    globex  grpc://agentkit-globex.agentkit.svc.cluster.local:50051;
  }

  map $http_authorization $agentkit_auth_present {
    default 1;
    ""      0;
  }

  server {
    listen 50051 http2;

    location /talk_api.AgentKit/Talk {
      # Reject calls that do not include required routing/auth metadata.
      if ($agentkit_auth_present = 0) {
        return 401;
      }

      if ($agentkit_backend = "") {
        return 403;
      }

      # Keep streams alive for long conversations.
      grpc_read_timeout 1h;
      grpc_send_timeout 1h;
      grpc_socket_keepalive on;

      # Forward routing/auth metadata to the selected backend.
      grpc_set_header tenant $http_tenant;
      grpc_set_header authorization $http_authorization;

      grpc_pass $agentkit_backend;
    }
  }
}
```

Configure Rapida with the NGINX address as the AgentKit endpoint:

```text theme={null}
agentkit-router.your-domain.com:50051
```

Then set per-call metadata when the conversation should go to a specific tenant pool:

```json theme={null}
{
  "options": {
    "agentkit.metadata": {
      "tenant": "acme",
      "authorization": "shared-token"
    }
  }
}
```

<Tip>
  If you use metadata key `x-tenant-id`, NGINX exposes it as `$http_x_tenant_id`. Hyphens become underscores in NGINX header variables.
</Tip>

### Kubernetes NGINX router

A Kubernetes `Service` can load balance between pods, but it cannot inspect AgentKit metadata. To route by metadata, run a gRPC-aware proxy such as NGINX in front of tenant-specific AgentKit services.

This example creates one public router service and two internal tenant backend services:

* `agentkit-acme`
* `agentkit-globex`

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: agentkit-nginx-router
  namespace: agentkit
data:
  nginx.conf: |
    worker_processes auto;

    events {
      worker_connections 65535;
    }

    http {
      resolver kube-dns.kube-system.svc.cluster.local valid=10s ipv6=off;

      map $http_tenant $agentkit_backend {
        default "";
        acme    grpc://agentkit-acme.agentkit.svc.cluster.local:50051;
        globex  grpc://agentkit-globex.agentkit.svc.cluster.local:50051;
      }

      map $http_authorization $agentkit_auth_present {
        default 1;
        ""      0;
      }

      server {
        listen 50051 http2;

        location /talk_api.AgentKit/Talk {
          if ($agentkit_auth_present = 0) {
            return 401;
          }

          if ($agentkit_backend = "") {
            return 403;
          }

          grpc_read_timeout 1h;
          grpc_send_timeout 1h;
          grpc_socket_keepalive on;

          grpc_set_header tenant $http_tenant;
          grpc_set_header authorization $http_authorization;

          grpc_pass $agentkit_backend;
        }
      }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentkit-nginx-router
  namespace: agentkit
spec:
  replicas: 2
  selector:
    matchLabels:
      app: agentkit-nginx-router
  template:
    metadata:
      labels:
        app: agentkit-nginx-router
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 50051
              name: grpc
          volumeMounts:
            - name: config
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
          readinessProbe:
            tcpSocket:
              port: grpc
            initialDelaySeconds: 5
            periodSeconds: 10
      volumes:
        - name: config
          configMap:
            name: agentkit-nginx-router
---
apiVersion: v1
kind: Service
metadata:
  name: agentkit-router
  namespace: agentkit
spec:
  type: LoadBalancer
  selector:
    app: agentkit-nginx-router
  ports:
    - name: grpc
      port: 50051
      targetPort: grpc
```

Point the Rapida AgentKit endpoint to the router service DNS name or load balancer DNS name.

Each tenant backend can be a normal Kubernetes `Deployment` and `Service`. The router selects the service based on metadata; the selected service then load-balances across that tenant's pods.

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: agentkit-acme
  namespace: agentkit
spec:
  selector:
    app: agentkit-acme
  ports:
    - name: grpc
      port: 50051
      targetPort: grpc
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentkit-acme
  namespace: agentkit
spec:
  replicas: 4
  selector:
    matchLabels:
      app: agentkit-acme
  template:
    metadata:
      labels:
        app: agentkit-acme
    spec:
      containers:
        - name: agentkit
          image: your-registry/agentkit-acme:latest
          ports:
            - containerPort: 50051
              name: grpc
          readinessProbe:
            grpc:
              port: 50051
            initialDelaySeconds: 5
            periodSeconds: 10
```

Repeat the backend `Service` and `Deployment` for each pool you reference in the NGINX `map`.

<Warning>
  Do not use tenant metadata as the only security boundary. Validate the metadata at the proxy or backend, and use token auth or signed routing claims when tenant isolation matters.
</Warning>

External references:

* [NGINX gRPC proxy module](https://nginx.org/en/docs/http/ngx_http_grpc_module.html)
* [Kubernetes liveness, readiness, and startup probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
* [gRPC health checking](https://grpc.io/docs/guides/health-checking/)

## Retries, failover, and draining

Retries are safe only before a stream is established. Once a conversation is active, retrying on another replica can duplicate tool calls or lose in-memory conversation state unless your backend is designed for resumability.

Recommended retry policy:

| Situation                             | Recommendation                                                                                  |
| ------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Initial connection fails              | Retry at the load balancer or client connection layer within the configured connect timeout.    |
| Stream opens but initialization fails | Treat as startup failure; retry only if your backend guarantees idempotent initialization.      |
| Active stream drops mid-conversation  | End or fail the conversation unless you have externalized state and a resume protocol.          |
| Tool call times out                   | Retry inside your AgentKit backend only when the tool is idempotent or has an idempotency key.  |
| Rolling deployment                    | Mark the replica unhealthy, stop new streams, wait for active streams to drain, then terminate. |

Production recommendations:

* Set `connectTimeoutMs` low enough to fail over quickly during startup, but high enough for your private network.
* Keep `keepaliveTimeMs` and `keepaliveTimeoutMs` aligned with your proxy and firewall timeouts.
* Use readiness checks that fail before shutdown so new streams stop landing on draining pods.
* Set a termination grace period long enough for normal conversations to finish.
* Make tool calls idempotent with a stable `tool_id` where possible.
* Store critical conversation state outside the process if the business requires recovery from pod failure.

## Customer checklist

* Benchmark safe active conversations per pod before production traffic.
* Configure Rapida with a load-balanced `agentKitUrl`.
* Use TLS and metadata-based auth for production.
* Route by metadata only through a gRPC-aware L7 proxy.
* Scale on active streams, latency, CPU, memory, and downstream provider limits.
* Drain pods before deploys.
* Treat active-stream failover as an application-level feature, not a load-balancer feature.


# Create Analysis for Assistant
Source: https://doc.rapida.ai/assistants/analysis/create-analysis

Step-by-step guide to setting up analysis for your AI assistant

This guide walks you through the process of setting up analysis functionality for your assistant to gain insights from conversations.

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Analysis" from the left sidebar menu.
    5. Click on **Create new analysis**.

       <img alt="Navigate to Analysis" />
  </Step>

  <Step title="Configure Analysis Details">
    <img alt="Configure Analysis Details" />

    Enter the basic information for your analysis:

    * **Name**: Provide a descriptive name for this analysis (e.g., "conversation-analysis")
    * **Description**: Add a brief explanation of what this analysis will do
  </Step>

  <Step title="Select Endpoint">
    <img alt="Select Endpoint" />

    Choose an endpoint that will process the analysis:

    * Select from existing endpoints in the dropdown
    * If you haven't created an appropriate endpoint, you'll need to create one first

    **Note**: The endpoint will receive the data specified in the parameters section and should be configured to process this information accordingly.
  </Step>

  <Step title="Configure Parameters">
    <img alt="Configure Parameters" />

    Set up the parameters that will be passed to your analysis endpoint:

    **Default Parameter**:

    * **Conversation Messages**: By default, the conversation history will be passed to the endpoint

    **Optional Additional Parameters**:

    <Step title="Configure Parameters">
      Add parameters to be sent with your API request:

      1. Click **Add parameters** to include data in your request
      2. Select the parameter type from the dropdown menu:

      <AccordionGroup>
        <Accordion title="Assistant">
          Include assistant-related information in the request:

          * Name
          * Prompt
        </Accordion>

        <Accordion title="Conversation">
          Include conversation data in the request:

          * Conversation history
        </Accordion>

        <Accordion title="Argument">
          * Include any arguments passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
        </Accordion>

        <Accordion title="Metadata">
          * Custom metadata that you want to send
        </Accordion>

        <Accordion title="Option">
          * Include configuration options passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
        </Accordion>
      </AccordionGroup>

      You can add multiple parameters to construct a complete API request.
    </Step>

    <img alt="Optional Parameters" />
  </Step>

  <Step title="Set Execution Priority">
    Set the execution priority for this analysis. This determines the order in
    which multiple analyses are processed if you have more than one.
  </Step>

  <Step title="Save Your Configuration">
    Click "Configure Analysis" to save your configuration.

    Once saved, your analysis will be available and will process conversations according to your settings. The results can be used for insights, improvements, or other downstream processes depending on your endpoint implementation.

    **Note**: Analysis functionality is currently in beta mode. Some features may be experimental or subject to change.
  </Step>
</Steps>

## Using Analysis Results

The analysis results will be processed by your specified endpoint, which can:

* Generate conversation insights
* Track user satisfaction
* Identify common questions or issues
* Provide metrics for assistant performance
* Feed data into your business intelligence tools using assistant webhooks.

## How to View Analysis

To view the analysis for a specific conversation:

1. Inside assistants, select the "Sessions" tab
2. Select the session that you want to view the analysis for
3. Click on the "Analysis" tab in the left panel.

You can view analysis results according to how your endpoint is configured to store and display this information.


# Overview
Source: https://doc.rapida.ai/assistants/analysis/overview

Step-by-step guide to setting up analysis for your AI assistant

Analysis is a powerful feature that allows you to gain insights from conversations with your AI assistant. This overview explains the key aspects of analysis functionality.

<img alt="Analysis" />

## What is Analysis?

Analysis in AI assistants is a process that examines conversation data to extract valuable information, metrics, and insights. It helps you understand how your assistant is performing and how users are interacting with it.

## Key Features of Analysis

1. **Customizable Configuration**: You can set up analysis with specific parameters tailored to your needs.

2. **Flexible Endpoints**: Choose or create endpoints that process the analysis data according to your requirements.

3. **Multiple Parameter Options**:

   * Conversation Messages (default)
   * Assistant Parameters (name, prompt)
   * Custom Arguments

4. **Execution Priority**: Set the order for processing multiple analyses.

5. **Integration with Business Intelligence**: Feed data into your BI tools using assistant webhooks.

## Benefits of Analysis

* Generate conversation insights
* Track user satisfaction
* Identify common questions or issues
* Measure assistant performance
* Inform improvements and optimizations

## Viewing Analysis Results

Analysis results can be viewed for specific conversations:

1. Go to the "Sessions" tab in your assistant
2. Select the desired session
3. Click on the "Analysis" tab in the left panel

The display of results depends on how your endpoint is configured to store and present the information.

## Usecase

<CardGroup>
  <Card title="Conversation Quality Analysis" icon="message-square">
    Evaluate the effectiveness of interactions between users and your AI assistant. This analysis helps improve coherence, relevance, and overall satisfaction in conversations.
  </Card>

  <Card title="Conversation Summaries" icon="file-text">
    Generate concise summaries of user interactions with your AI assistant, allowing for quick understanding of main points and efficient review of engagements.
  </Card>

  <Card title="Extracting Structured Information" icon="database">
    Transform unstructured conversation data into structured, actionable insights, enabling advanced analytics and seamless integration with other systems.
  </Card>

  <Card title="User Intent Classification" icon="target">
    Categorize and understand the primary goals of your users, helping to improve assistant responses and tailor your offerings to user needs.
  </Card>

  <Card title="Sentiment Analysis" icon="smile">
    Gauge the emotional tone of user interactions with your AI assistant, allowing you to track satisfaction trends and adjust responses accordingly.
  </Card>

  <Card title="Knowledge Gap Identification" icon="search">
    Uncover areas where your AI assistant lacks information or struggles to provide accurate responses, helping prioritize improvements to its knowledge base.
  </Card>
</CardGroup>

## Note

Analysis functionality is currently in beta mode. Some features may be experimental or subject to change.

<Card title="Creating an Endpoint for Analysis">
  To use the analysis feature, you need to create an endpoint that will process the analysis data.

  [Learn more about creating endpoints](/endpoint/overview)
</Card>


# Update Analysis for Assistant
Source: https://doc.rapida.ai/assistants/analysis/update-analysis

Step-by-step guide to update analysis for your AI assistant

This guide walks you through the process of setting up analysis functionality for your assistant to gain insights from conversations.

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Analysis" from the left sidebar menu.
    5. Click on **Create new analysis**.

       <img alt="Navigate to Analysis" />
  </Step>

  <Step title="Configure Analysis Details">
    <img alt="Configure Analysis Details" />

    Enter the basic information for your analysis:

    * **Name**: Provide a descriptive name for this analysis (e.g., "conversation-analysis")
    * **Description**: Add a brief explanation of what this analysis will do
  </Step>

  <Step title="Select Endpoint">
    <img alt="Select Endpoint" />

    Choose an endpoint that will process the analysis:

    * Select from existing endpoints in the dropdown
    * If you haven't created an appropriate endpoint, you'll need to create one first

    **Note**: The endpoint will receive the data specified in the parameters section and should be configured to process this information accordingly.
  </Step>

  <Step title="Configure Parameters">
    <img alt="Configure Parameters" />

    Set up the parameters that will be passed to your analysis endpoint:

    **Default Parameter**:

    * **Conversation Messages**: By default, the conversation history will be passed to the endpoint

    **Optional Additional Parameters**:

    <Step title="Configure Parameters">
      Add parameters to be sent with your API request:

      1. Click **Add parameters** to include data in your request
      2. Select the parameter type from the dropdown menu:

      <AccordionGroup>
        <Accordion title="Assistant">
          Include assistant-related information in the request:

          * Name
          * Prompt
        </Accordion>

        <Accordion title="Conversation">
          Include conversation data in the request:

          * Conversation history
        </Accordion>

        <Accordion title="Argument">
          * Include any arguments passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
        </Accordion>

        <Accordion title="Metadata">
          * Custom metadata that you want to send
        </Accordion>

        <Accordion title="Option">
          * Include configuration options passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
        </Accordion>
      </AccordionGroup>

      You can add multiple parameters to construct a complete API request.
    </Step>

    <img alt="Optional Parameters" />
  </Step>

  <Step title="Set Execution Priority">
    Set the execution priority for this analysis. This determines the order in
    which multiple analyses are processed if you have more than one.
  </Step>

  <Step title="Save Your Configuration">
    Click "Configure Analysis" to save your configuration.

    Once saved, your analysis will be available and will process conversations according to your settings. The results can be used for insights, improvements, or other downstream processes depending on your endpoint implementation.

    **Note**: Analysis functionality is currently in beta mode. Some features may be experimental or subject to change.
  </Step>
</Steps>

## Using Analysis Results

The analysis results will be processed by your specified endpoint, which can:

* Generate conversation insights
* Track user satisfaction
* Identify common questions or issues
* Provide metrics for assistant performance
* Feed data into your business intelligence tools using assistant webhooks.

## How to View Analysis

To view the analysis for a specific conversation:

1. Inside assistants, select the "Sessions" tab
2. Select the session that you want to view the analysis for
3. Click on the "Analysis" tab in the left panel.

You can view analysis results according to how your endpoint is configured to store and display this information.


# Authentication
Source: https://doc.rapida.ai/assistants/configuration/authentication

Configure conversation-time authentication from Rapida Console.

Assistant authentication runs at the start of a conversation. Rapida calls your authentication service before the assistant, tools, STT, TTS, or AgentKit backend starts. Use it to verify the user, tenant, subscription, account state, or channel context for the live session.

<Info>
  This is not Rapida API authentication. Rapida API authentication controls who can manage assistants and start sessions. Assistant authentication controls whether one conversation should continue, and what extra context should be added to that conversation.
</Info>

```mermaid theme={null}
flowchart LR
    A["Conversation starts"] --> B["Load assistant"]
    B --> C["Run authentication"]
    C --> D{"Result"}
    D -->|2xx| E["Merge overrides"]
    D -->|Skipped or allowed| F["Continue unauthenticated"]
    D -->|Blocked failure| G["Stop session"]
    E --> H["Start assistant runtime"]
    F --> H
```

## Configure in Rapida Console

<Steps>
  <Step title="Open the assistant">
    In Rapida Console, open the assistant you want to protect.
  </Step>

  <Step title="Open Configure Assistant">
    Go to **Configure Assistant** and open the **Authentication** configuration.
  </Step>

  <Step title="Enable authentication">
    Turn on authentication for the assistant. If authentication is disabled or no authentication configuration exists, Rapida skips this step and the conversation continues normally.
  </Step>

  <Step title="Select HTTP provider">
    Choose **HTTP** as the authentication provider. HTTP is the supported provider for assistant authentication.
  </Step>

  <Step title="Enter endpoint details">
    Add the authentication endpoint URL, method, timeout, static headers, and request body mapping.
  </Step>

  <Step title="Choose failure behavior">
    Use **Block** when authentication is required. Use **Allow** only when the endpoint is used for optional enrichment.
  </Step>

  <Step title="Save and test">
    Save the configuration, then test from the target channel, such as Debugger, Phone Call, Web Widget, Web App, or WhatsApp.
  </Step>
</Steps>

## What to configure

| Console field          | Runtime key                | Required | Description                                                                                                 |
| ---------------------- | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| Provider               | `provider=http`            | Yes      | Calls an external HTTP service. Other providers are not supported for assistant authentication.             |
| Endpoint URL           | `http_url`                 | Yes      | Full URL of your authentication endpoint.                                                                   |
| Method                 | `http_method`              | No       | Defaults to `POST`. Supported write methods are `POST`, `PUT`, and `PATCH`; other values are sent as `GET`. |
| Headers                | `http_headers`             | No       | Static headers sent to the authentication endpoint. Use this for fixed integration headers.                 |
| Body mapping           | `http_body`                | Yes      | Maps Rapida conversation variables into the JSON body sent to your endpoint.                                |
| Timeout                | `timeout_ms`               | No       | Defaults to `5000` milliseconds.                                                                            |
| Failure behavior       | `fail_behavior`            | No       | Defaults to `block`. Controls non-`2xx` authentication responses.                                           |
| Apply when / condition | `authentication.condition` | No       | Limits authentication to specific source, mode, or direction values.                                        |

<Warning>
  Configure a valid body mapping. If the body mapping is missing or invalid, Rapida cannot build authentication arguments and the session continues unauthenticated.
</Warning>

## Request body mapping

The body mapping is not a literal JSON body. It maps **source variables** to **request body field names**.

Example body mapping:

```json theme={null}
{
  "client.phone": "phone",
  "metadata.tenant": "tenant",
  "conversation.id": "conversationId",
  "argument.customerId": "customerId",
  "custom.source": "rapida"
}
```

If the session has phone `+14155550123`, tenant `acme`, conversation ID `2230142097179373568`, and argument `customerId=cust_123`, Rapida sends this body:

```json theme={null}
{
  "phone": "+14155550123",
  "tenant": "acme",
  "conversationId": "2230142097179373568",
  "customerId": "cust_123",
  "source": "rapida"
}
```

Use these namespaces in the mapping:

| Namespace        | Example                                | Use for                                                                                                  |
| ---------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `assistant.*`    | `"assistant.id": "assistantId"`        | Active assistant fields.                                                                                 |
| `conversation.*` | `"conversation.id": "conversationId"`  | Current conversation fields.                                                                             |
| `session.*`      | `"session.source": "source"`           | Session source and mode.                                                                                 |
| `argument.*`     | `"argument.customerId": "customerId"`  | Runtime arguments passed when the session starts.                                                        |
| `metadata.*`     | `"metadata.tenant": "tenant"`          | Conversation metadata.                                                                                   |
| `option.*`       | `"option.agentkit.url": "agentkitUrl"` | Runtime options.                                                                                         |
| `client.*`       | `"client.phone": "phone"`              | Client metadata projected from `metadata.client.*`.                                                      |
| `custom.*`       | `"custom.source": "rapida"`            | Literal values. The suffix becomes the request field name and the value becomes the request field value. |

Unknown or unavailable variables are skipped. Your authentication service should reject requests that are missing required fields.

## Endpoint response

Return any `2xx` status code to authenticate the session. The response body can be empty, or it can return overrides that Rapida merges before the assistant runtime starts.

```json theme={null}
{
  "args": {
    "customerName": "Jane",
    "plan": "enterprise"
  },
  "metadata": {
    "customerId": "cust_123",
    "tenant": "acme"
  },
  "options": {
    "experience.greeting": "Hi Jane, I found your account.",
    "agentkit.metadata": {
      "tenant": "acme",
      "customerId": "cust_123"
    }
  }
}
```

| Response field        | What it does                                                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `args` or `arguments` | Adds or overrides runtime arguments. Use these for prompt variables such as customer name, plan, case ID, or order ID.                    |
| `metadata`            | Adds or overrides conversation metadata. Use these for tenant, customer ID, routing label, audit ID, or authenticated user ID.            |
| `options`             | Adds or overrides runtime options. Use these for dynamic greeting, AgentKit metadata, model settings, or other supported runtime options. |

Returned values override existing values with the same key. Nested maps are merged, so returning `agentkit.metadata.tenant` can add tenant routing context without replacing unrelated AgentKit metadata.

## Failure behavior

| Situation                                                                                         | Result                                                                                |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| No authentication configuration                                                                   | Authentication is skipped and the conversation continues.                             |
| Authentication disabled                                                                           | Authentication is skipped and the conversation continues.                             |
| Condition does not match                                                                          | Authentication is skipped and the conversation continues unauthenticated.             |
| Missing or invalid body mapping                                                                   | Authentication arguments cannot be built; the conversation continues unauthenticated. |
| Missing endpoint URL                                                                              | Authentication execution fails and the session stops.                                 |
| Endpoint timeout or network error                                                                 | Authentication execution fails and the session stops.                                 |
| Endpoint returns `2xx`                                                                            | Session is authenticated. Returned `args`, `metadata`, and `options` are merged.      |
| Endpoint returns non-`2xx` and failure behavior is `block`                                        | Session stops before the assistant starts.                                            |
| Endpoint returns non-`2xx` and failure behavior is `allow`, `none`, `do_nothing`, or `do-nothing` | Session continues unauthenticated. Returned overrides are not applied.                |

Use `block` for login, subscription, tenant authorization, compliance, or account access checks. Use `allow` only when authentication is being used as optional personalization or lookup.

## Conditions

Conditions let one assistant use authentication only for specific channels or session types. The supported condition keys are:

| Key                           | Allowed values                                                            |
| ----------------------------- | ------------------------------------------------------------------------- |
| `source`                      | `all`, `sdk`, `web_plugin`, `debugger`, `phone`, `phone-call`, `whatsapp` |
| `mode` or `conversation_mode` | `all`, `text`, `voice`, `audio`                                           |
| `direction`                   | `both`, `all`, `inbound`, `outbound`                                      |

If multiple rules are configured, all rules must match. If the condition is malformed, authentication is treated as not allowed and the session continues unauthenticated.

Example condition for inbound phone voice sessions:

```json theme={null}
[
  {
    "key": "source",
    "condition": "=",
    "value": "phone"
  },
  {
    "key": "mode",
    "condition": "=",
    "value": "voice"
  },
  {
    "key": "direction",
    "condition": "=",
    "value": "inbound"
  }
]
```

## Dynamic AgentKit routing

Assistant authentication can return AgentKit metadata in `options`. Rapida merges it before opening the AgentKit stream, so your AgentKit backend or load balancer can use authenticated tenant or customer context.

```json theme={null}
{
  "options": {
    "agentkit.metadata": {
      "tenant": "acme",
      "customerTier": "enterprise",
      "authorization": "Bearer backend-session-token"
    }
  }
}
```

Use metadata for distribution labels such as `tenant`, `region`, or `customerShard`. Keep authorization checks in the AgentKit backend as well; load-balancer routing should not be the only security control.

See [Scale AgentKit backends](/assistants/agentkit/scaling) for metadata-based routing examples.

## Recommended setup

| Area             | Recommendation                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| Failure behavior | Start with `block` for any real access control.                                                               |
| Timeout          | Start with `5000` ms, then lower after measuring endpoint latency.                                            |
| Body mapping     | Include all fields your auth service needs to make a deterministic allow/deny decision.                       |
| Required fields  | Validate required fields in your auth service and return non-`2xx` when they are missing.                     |
| Overrides        | Return only context the assistant, tools, AgentKit backend, routing layer, or logs need.                      |
| Secrets          | Do not pass long-lived secrets from public clients. Use short-lived session tokens or server-side validation. |

## Related

<CardGroup>
  <Card title="Experience" icon="sliders-horizontal" href="/assistants/configuration/experience">
    Use authentication overrides to adjust greeting and session behavior.
  </Card>

  <Card title="AgentKit" icon="bot" href="/assistants/agentkit">
    Run assistant logic in your own AgentKit backend.
  </Card>

  <Card title="Scale AgentKit backends" icon="network" href="/assistants/agentkit/scaling">
    Route AgentKit traffic by authenticated metadata.
  </Card>

  <Card title="Telemetry" icon="activity" href="/assistants/telemetry">
    Export conversation events and runtime metadata.
  </Card>
</CardGroup>


# Experience
Source: https://doc.rapida.ai/assistants/configuration/experience

Define shared session behavior for assistant deployments.

Experience settings control how a deployment behaves during a live session: what the assistant says first, what happens when the user goes quiet, how long the session can run, and which starter prompts appear in supported channels.

These settings are configured per deployment. The same assistant can use different experience settings for Phone Call, Web Widget, Web App / SDK, WhatsApp, and Debugger deployments.

<Info>
  Experience settings are separate from [Listen](/assistants/configuration/listen) and [Speak](/assistants/configuration/speak) settings. Use Listen for speech-to-text, VAD, noise cancellation, and end-of-speech configuration. Use Speak for text-to-speech, voice, pronunciation, and speech delivery.
</Info>

## Parameter reference

| Dashboard label          | SDK / API field                 | Type             | Default                                       | Range                | Description                                                                                                                                                 |
| ------------------------ | ------------------------------- | ---------------- | --------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Greeting                 | `greeting`                      | `string`         | None                                          | Any text             | First message sent when a session starts. In voice deployments, this is spoken. In text deployments, this is shown as the first assistant message.          |
| Greeting interruptible   | `greetingInterruptible`         | `boolean`        | `true`                                        | `true` / `false`     | Controls whether users can interrupt the opening greeting in audio sessions. Set to `false` when the full greeting must be heard before the user can speak. |
| Error message            | `mistake`                       | `string`         | None                                          | Any text             | Fallback message used when the assistant cannot understand the user input, cannot handle the request, or hits an unrecoverable runtime error.               |
| Unclear input timeout    | `unclearInputTimeout`           | `double` seconds | `0.5`                                         | `0.5`-`5`            | Time to wait after interrupted or unclear input before asking the user to repeat.                                                                           |
| Unclear input message    | `unclearInputMessage`           | `string`         | `I didn't catch that. Could you repeat that?` | Up to 250 characters | Message sent when the assistant could not understand the user input.                                                                                        |
| Idle silence timeout     | `idealTimeout`                  | `uint64` seconds | `30`                                          | `5`-`120`            | Time to wait for user input before sending the idle message.                                                                                                |
| Idle timeout backoff     | `idealTimeoutBackoff`           | `uint64`         | `2`                                           | `0`-`5`              | Number of idle-timeout retries before the inactive session is allowed to end.                                                                               |
| Idle message             | `idealTimeoutMessage`           | `string`         | `Are you there?`                              | Any text             | Message sent when the idle silence timeout expires without user input.                                                                                      |
| Maximum session duration | `maxSessionDuration`            | `uint64` seconds | `300`                                         | `180`-`600`          | Hard cap on session length. The session ends when this limit is reached, even if the user is active.                                                        |
| Quickstart questions     | `suggestion` / `suggestionList` | `string[]`       | None                                          | List of text prompts | Starter prompts shown as clickable options in the Web Widget home screen.                                                                                   |

<Note>
  Generated SDK method names vary by language. For example, the JavaScript SDK uses setters such as `setGreeting`, `setMistake`, and `setIdealtimeout`. The logical field names above match the deployment API and SDK reference pages.
</Note>

## Runtime overrides

You can override experience settings for a single outbound phone call by passing experience options when creating the call. Runtime overrides do not update the saved Phone Call deployment; they only apply to the conversation being created.

Use the `options` map on `CreatePhoneCallRequest` with `experience.*` keys:

```json theme={null}
{
  "assistant": {
    "assistantId": "2230142097179373568",
    "version": "latest"
  },
  "toNumber": "+14155550123",
  "fromNumber": "+14155550100",
  "args": {
    "name": "Jane"
  },
  "options": {
    "experience.greeting": "Hi {{name}}, this is Rapida calling about your appointment.",
    "experience.greeting_interruptible": false,
    "experience.mistake": "Sorry, I did not understand that.",
    "experience.unclear_input_timeout": 0.5,
    "experience.unclear_input_message": "I didn't catch that. Could you repeat that?",
    "experience.ideal_timeout": 30,
    "experience.ideal_timeout_backoff": 2,
    "experience.ideal_timeout_message": "Are you still there?",
    "experience.max_session_duration": 300
  }
}
```

For bulk outbound calls, pass the same `options` object on each `CreatePhoneCallRequest` inside the bulk request. This lets each recipient receive a different greeting, timeout policy, or session duration.

| Option key                          | Type             | Overrides               | Description                                                                                              |
| ----------------------------------- | ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- |
| `experience.greeting`               | `string`         | `greeting`              | Opening message for this call. Supports the same `{{variable}}` syntax as the saved deployment greeting. |
| `experience.greeting_interruptible` | `boolean`        | `greetingInterruptible` | Controls whether the caller can interrupt the opening greeting.                                          |
| `experience.mistake`                | `string`         | `mistake`               | Error or fallback message for this call.                                                                 |
| `experience.unclear_input_timeout`  | `number` seconds | `unclearInputTimeout`   | Time to wait after interrupted or unclear input before asking the caller to repeat.                      |
| `experience.unclear_input_message`  | `string`         | `unclearInputMessage`   | Message sent when the assistant could not understand the caller input.                                   |
| `experience.ideal_timeout`          | `number` seconds | `idealTimeout`          | Idle silence timeout for this call.                                                                      |
| `experience.ideal_timeout_backoff`  | `number`         | `idealTimeoutBackoff`   | Number of idle prompts before the inactive call can end.                                                 |
| `experience.ideal_timeout_message`  | `string`         | `idealTimeoutMessage`   | Message sent when the idle timeout expires.                                                              |
| `experience.max_session_duration`   | `number` seconds | `maxSessionDuration`    | Hard session duration limit for this call.                                                               |

<Tip>
  Use `args` for values you want to interpolate into prompts, such as `{{name}}`. Use `options` for runtime experience overrides, such as `experience.greeting` or `experience.max_session_duration`.
</Tip>

## Session lifecycle

<Steps>
  <Step title="Session starts">
    Rapida creates a session for the selected deployment and sends the configured `greeting`.
  </Step>

  <Step title="User becomes inactive">
    If no user input arrives within `idealTimeout`, Rapida sends `idealTimeoutMessage`.
  </Step>

  <Step title="Input is unclear">
    If the user interrupts but does not continue, or speech is not recognized confidently, Rapida waits for `unclearInputTimeout` and then sends `unclearInputMessage`.
  </Step>

  <Step title="Idle retries are exhausted">
    `idealTimeoutBackoff` controls how many idle prompts can be sent before the inactive session is allowed to end.
  </Step>

  <Step title="Session reaches its hard limit">
    `maxSessionDuration` ends the session regardless of idle state. Use this to prevent runaway calls, long browser sessions, or abandoned conversations.
  </Step>
</Steps>

## Greeting variables

Use `{{variable}}` syntax in the greeting when the deployment receives runtime arguments.

For Web App / SDK public URLs, query parameters are available to the greeting:

```text theme={null}
https://app.rapida.ai/preview/public/assistant/{ASSISTANT_ID}?token={KEY}&name=John
```

```text theme={null}
Hello {{name}}, how can I help you today?
```

For outbound phone calls, pass runtime values through call `args` and reference the matching variable names in the greeting.

## Quickstart questions

Quickstart questions are only used by Web Widget deployments. They appear below the greeting as clickable prompts that help users start a conversation without typing.

Good quickstart questions are short, specific, and action-oriented:

| Good                    | Avoid                           |
| ----------------------- | ------------------------------- |
| `Book a demo`           | `How can I use this assistant?` |
| `Check my order status` | `Tell me more`                  |
| `Talk to support`       | `Question`                      |

## Recommended defaults

Use these defaults for most deployments unless the channel needs different behavior.

| Setting                  | Recommended value                             | Notes                                                                         |
| ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------- |
| Greeting                 | A short channel-specific opener               | Voice greetings should be speakable in one sentence.                          |
| Greeting interruptible   | `true`                                        | Set to `false` only when callers must hear the full greeting before speaking. |
| Error message            | `Sorry, I did not understand that.`           | Keep it short and avoid exposing internal errors.                             |
| Unclear input timeout    | `0.5`                                         | Increase only when users often pause after an interruption.                   |
| Unclear input message    | `I didn't catch that. Could you repeat that?` | Keep it short and ask for a repeat.                                           |
| Idle silence timeout     | `30`                                          | Lower values feel faster; higher values give users more time to respond.      |
| Idle timeout backoff     | `2`                                           | Gives the user two chances before ending an inactive session.                 |
| Idle message             | `Are you still there?`                        | Use a neutral prompt that works across channels.                              |
| Maximum session duration | `300`                                         | Five minutes is a good starting point for calls and live web sessions.        |

## SDK / API shape

The same experience fields appear across deployment variants:

```json theme={null}
{
  "greeting": "Hi {{name}}, how can I help you today?",
  "greetingInterruptible": true,
  "mistake": "Sorry, I did not understand that.",
  "unclearInputTimeout": 0.5,
  "unclearInputMessage": "I didn't catch that. Could you repeat that?",
  "idealTimeout": 30,
  "idealTimeoutBackoff": 2,
  "idealTimeoutMessage": "Are you still there?",
  "maxSessionDuration": 300
}
```

Web Widget deployments can also include quickstart questions:

```json theme={null}
{
  "suggestion": ["Book a demo", "Talk to support", "Check my order status"]
}
```

## Related

<CardGroup>
  <Card title="Phone Call" icon="phone" href="/voice-deployment-options/phone">
    Configure experience settings for inbound and outbound calls.
  </Card>

  <Card title="Web Widget" icon="message-square" href="/voice-deployment-options/web-widget">
    Add greeting text, quickstart questions, and widget behavior.
  </Card>

  <Card title="Listen" icon="mic" href="/assistants/configuration/listen">
    Configure speech-to-text, noise cancellation, VAD, and end-of-speech.
  </Card>

  <Card title="Speak" icon="volume-2" href="/assistants/configuration/speak">
    Configure text-to-speech, voices, pronunciation, and spoken output.
  </Card>
</CardGroup>


# Listen
Source: https://doc.rapida.ai/assistants/configuration/listen

Configure how Rapida captures, cleans, detects, and transcribes user speech.

Listen settings control how Rapida handles user audio before the assistant responds. Use this section for `listen.*` runtime options and deployment settings related to speech-to-text, noise cancellation, voice activity detection, and end-of-speech.

```mermaid theme={null}
flowchart LR
    A["User audio"] --> B["Noise cancellation"]
    B --> C["Voice Activity Detection"]
    C --> D["Speech-to-Text"]
    D --> E["End of Speech"]
    E --> F["LLM + tools"]
```

<Info>
  Listen settings are used by voice-capable deployments: Phone Call, Web Widget with microphone input, and Web App / SDK with microphone input. Text-only channels do not use listen configuration.
</Info>

## Configure it

Open your assistant, select **Configure Assistant**, then open **Deployments**. Listen settings appear in the **Voice Input** step for each deployment that supports microphone or phone audio.

| Area                     | What it controls                                                   |
| ------------------------ | ------------------------------------------------------------------ |
| Speech-to-Text           | Provider, credential, model, language, and transcription behavior. |
| Noise cancellation       | Background noise removal before VAD and STT.                       |
| Voice Activity Detection | Speech start/stop detection and barge-in sensitivity.              |
| End of Speech            | Turn completion detection and silence timeout behavior.            |

## Configuration pages

<CardGroup>
  <Card title="Speech-to-Text" icon="mic" href="/assistants/speech-to-text">
    Choose the provider, credential, model, and language used to transcribe user speech.
  </Card>

  <Card title="Noise Cancellation" icon="audio-waveform" href="/assistants/noise-cancellation">
    Clean background noise before VAD and STT process the user's audio.
  </Card>

  <Card title="Voice Activity Detection" icon="activity" href="/assistants/voice-activity-detection">
    Tune speech detection, silence frames, and barge-in sensitivity.
  </Card>

  <Card title="End of Speech Detection" icon="clock" href="/assistants/end-of-speech">
    Decide when the user has finished a turn and the assistant should respond.
  </Card>
</CardGroup>

## Recommended starting point

| Area               | Start with                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------ |
| STT                | A streaming provider and model that matches your channel audio.                            |
| Noise cancellation | RNNoise enabled for phone calls and noisy browser environments.                            |
| VAD                | Silero VAD.                                                                                |
| EOS                | Pipecat Smart Turn for natural conversations, or Silence-Based for simple IVR-style flows. |

<Tip>
  Tune listen settings from real conversation logs. If a caller gets cut off, start with EOS and VAD. If transcription is wrong, check language, audio quality, noise cancellation, and STT model.
</Tip>

## Runtime overrides

You can override listen settings for a single outbound phone call by passing `listen.*` keys in `CreatePhoneCallRequest.options`. Runtime overrides do not update the saved deployment.

```json theme={null}
{
  "options": {
    "listen.language": "en",
    "listen.model": "nova-3",
    "listen.threshold": 0.75,
    "listen.audio.encoding": "mulaw",
    "listen.audio.sample_rate": 8000,
    "listen.smart_format": true,
    "listen.filler_words": false,
    "listen.endpointing": "300"
  }
}
```

| Option key                 | Type                  | Description                                                                           |
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
| `listen.language`          | `string`              | Primary transcription language or provider language code.                             |
| `listen.model`             | `string`              | Provider-specific STT model for this call.                                            |
| `listen.threshold`         | `number`              | Speech detection threshold used by supported providers.                               |
| `listen.audio.encoding`    | `string`              | Input audio encoding, such as `mulaw` or `pcm_s16le`, when supported by the provider. |
| `listen.audio.sample_rate` | `number`              | Input audio sample rate, such as `8000` for telephony audio.                          |
| `listen.region`            | `string`              | Provider region for services that support regional endpoints.                         |
| `listen.smart_format`      | `boolean`             | Enables provider smart formatting when supported.                                     |
| `listen.filler_words`      | `boolean`             | Controls filler-word transcription when supported.                                    |
| `listen.vad_events`        | `boolean`             | Enables provider VAD events when supported.                                           |
| `listen.endpointing`       | `string`              | Provider endpointing or silence setting.                                              |
| `listen.multichannel`      | `boolean`             | Enables multichannel transcription when supported.                                    |
| `listen.keyword`           | `string` / `string[]` | Provider keyword boosting terms.                                                      |
| `listen.operating_point`   | `string`              | Provider accuracy/latency tier, such as Speechmatics operating point.                 |
| `listen.query_params`      | JSON object string    | Custom STT provider query parameters.                                                 |
| `listen.request_rules`     | JSON array string     | Custom STT request DSL rules.                                                         |
| `listen.response_rules`    | JSON array string     | Custom STT response DSL rules.                                                        |

## Troubleshooting map

| Symptom                                            | First place to look                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Assistant responds before the user is done         | [End of Speech Detection](/assistants/end-of-speech)                                                                      |
| Assistant interrupts on coughs or background noise | [Voice Activity Detection](/assistants/voice-activity-detection) and [Noise Cancellation](/assistants/noise-cancellation) |
| Transcript is wrong or incomplete                  | [Speech-to-Text](/assistants/speech-to-text)                                                                              |
| Phone calls behave differently from web sessions   | Deployment-level Voice Input settings                                                                                     |

## Related

<CardGroup>
  <Card title="Experience" icon="sliders-horizontal" href="/assistants/configuration/experience">
    Configure greeting, idle timeout, error message, and session duration.
  </Card>

  <Card title="Speak" icon="volume-2" href="/assistants/configuration/speak">
    Configure text-to-speech and spoken output.
  </Card>

  <Card title="Phone Call Deployment" icon="phone" href="/voice-deployment-options/phone">
    Configure required voice input for phone calls.
  </Card>

  <Card title="Web App / SDK Deployment" icon="monitor" href="/voice-deployment-options/web-app">
    Configure optional voice input for custom apps.
  </Card>
</CardGroup>


# Speak
Source: https://doc.rapida.ai/assistants/configuration/speak

Configure how Rapida turns assistant responses into spoken output.

Speak settings control how assistant text becomes audio. Use this section for `speak.*` runtime options and deployment settings related to text-to-speech, voices, pronunciation, ambient audio, and speech delivery.

```mermaid theme={null}
flowchart LR
    A["LLM + tools"] --> B["Assistant text"]
    B --> C["Text-to-Speech"]
    C --> D["User hears response"]
```

<Info>
  Speak settings are used by voice-capable deployments: Phone Call, Web Widget with spoken responses, and Web App / SDK with spoken responses. Text-only channels do not use speak configuration.
</Info>

## Configure it

Open your assistant, select **Configure Assistant**, then open **Deployments**. Speak settings appear in the **Voice Output** step for each deployment that supports spoken responses.

| Area           | What it controls                                                                   |
| -------------- | ---------------------------------------------------------------------------------- |
| Text-to-Speech | Provider, credential, model, voice, language, and speech synthesis behavior.       |
| Pronunciation  | How dates, times, numbers, addresses, URLs, acronyms, and domain terms are spoken. |
| Delivery       | Pause behavior, conjunction boundaries, and optional ambient audio.                |

## Configuration pages

<CardGroup>
  <Card title="Text-to-Speech" icon="volume-2" href="/assistants/text-to-speech">
    Choose the provider, voice, model, language, pronunciation, and speech delivery settings.
  </Card>

  <Card title="Custom TTS" icon="settings" href="/integrations/tts/custom">
    Connect a custom WebSocket speech synthesis provider with DSL rules.
  </Card>
</CardGroup>

## Recommended starting point

| Area          | Start with                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| TTS           | A low-latency streaming voice that supports the assistant's primary language.                               |
| Pronunciation | Enable dictionaries for numbers, currency, dates, times, URLs, and domain terms that users will hear often. |
| Prompt        | Short spoken responses, usually one or two sentences.                                                       |

<Tip>
  Tune speak settings by listening to full conversations in the target channel. A voice that sounds good in a browser preview can still sound unclear over phone audio.
</Tip>

## Runtime overrides

You can override speak settings for a single outbound phone call by passing `speak.*` or `speaker.*` keys in `CreatePhoneCallRequest.options`. Runtime overrides do not update the saved deployment.

```json theme={null}
{
  "options": {
    "speak.voice.id": "VOICE_ID_PLACEHOLDER",
    "speak.language": "en",
    "speak.model": "sonic-2",
    "speak.audio.encoding": "mulaw",
    "speak.audio.sample_rate": 8000,
    "speaker.conjunction.boundaries": "and<|||>but<|||>or",
    "speaker.conjunction.break": 240
  }
}
```

| Option key                              | Type               | Description                                               |
| --------------------------------------- | ------------------ | --------------------------------------------------------- |
| `speak.voice.id`                        | `string`           | TTS voice ID for this call.                               |
| `speak.language`                        | `string`           | Output speech language or provider language code.         |
| `speak.model`                           | `string`           | Provider-specific TTS model.                              |
| `speak.audio.encoding`                  | `string`           | Output audio encoding when supported by the provider.     |
| `speak.audio.sample_rate`               | `number`           | Output audio sample rate.                                 |
| `speak.query_params`                    | JSON object string | Custom TTS provider query parameters.                     |
| `speak.request_rules`                   | JSON array string  | Custom TTS request DSL rules.                             |
| `speak.response_rules`                  | JSON array string  | Custom TTS response DSL rules.                            |
| `speak.__experimental_controls.speed`   | `string`           | Provider-specific experimental speed control.             |
| `speak.__experimental_controls.emotion` | `string`           | Provider-specific experimental emotion control.           |
| `speak.speed_alpha`                     | `string`           | Provider-specific speed alpha control.                    |
| `speak.speed`                           | `string`           | Provider-specific speaking speed.                         |
| `speaker.language`                      | `string`           | Speaker normalization language.                           |
| `speaker.voice.name`                    | `string`           | Human-readable speaker or voice name.                     |
| `speaker.conjunction.boundaries`        | `string`           | Delimiter-separated words where Rapida can insert pauses. |
| `speaker.conjunction.break`             | `number`           | Pause duration at conjunction boundaries in milliseconds. |
| `speaker.pronunciation.dictionaries`    | `string`           | Pronunciation dictionary configuration.                   |
| `speaker.ambient`                       | `string`           | Ambient audio preset.                                     |
| `speaker.ambient_volume`                | `number`           | Ambient audio volume.                                     |

## Troubleshooting map

| Symptom                                          | First place to look                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Assistant voice starts slowly                    | [Text-to-Speech](/assistants/text-to-speech) model latency and response length       |
| Assistant mispronounces product names or numbers | [Text-to-Speech](/assistants/text-to-speech) pronunciation dictionaries              |
| Assistant sounds rushed                          | Conjunction boundaries, pause duration, and prompt response length                   |
| Voice sounds poor on phone                       | Test through [Phone Call](/voice-deployment-options/phone), not only browser preview |

## Related

<CardGroup>
  <Card title="Experience" icon="sliders-horizontal" href="/assistants/configuration/experience">
    Configure greeting, idle timeout, error message, and session duration.
  </Card>

  <Card title="Listen" icon="mic" href="/assistants/configuration/listen">
    Configure speech-to-text, VAD, noise cancellation, and end-of-speech.
  </Card>

  <Card title="Phone Call Deployment" icon="phone" href="/voice-deployment-options/phone">
    Configure required voice output for phone calls.
  </Card>

  <Card title="Web Widget Deployment" icon="message-square" href="/voice-deployment-options/web-widget">
    Configure optional spoken responses in the web widget.
  </Card>
</CardGroup>


# Create and Configure an Assistant
Source: https://doc.rapida.ai/assistants/create-assistant

Build a production-ready voice AI assistant — from prompt definition to runtime configuration, tools, knowledge, and deployment.

An assistant is the central object in Rapida. It holds your LLM configuration, system prompt, experience, listen and speak settings, tools, knowledge bases, and deployment channels — all versioned and deployable across phone, web, and messaging from one place.

<Info>
  Before creating an assistant, set up credentials for your LLM, STT, and TTS providers in **Integration → Vault**. The creation wizard will ask you to select a provider — credentials must exist first.
</Info>

## Create your first assistant

<Steps>
  <Step title="Navigate to Assistants">
    <img alt="Navigate to Assistants" />

    Go to **Assistants** in the main sidebar. Click **Add new assistant** to open the creation wizard.
  </Step>

  <Step title="Select your LLM provider and model">
    <img alt="Select your LLM" />

    Choose your LLM provider and the specific model to power this assistant. Supported providers: [OpenAI](/integrations/llm/openai), [Anthropic](/integrations/llm/anthropic), [Azure OpenAI](/integrations/llm/azure-openai), [Google Gemini](/integrations/llm/google-ai), [Cohere](/integrations/llm/cohere), [Vertex AI](/integrations/llm/google-vertex-ai), or a custom [AgentKit](/assistants/agentkit) gRPC backend.

    Each provider requires a vault credential. The model you select here sets the default — you can tune all parameters after creation.
  </Step>

  <Step title="Write your system prompt">
    <img alt="Provide Assistant Instructions" />

    Define the assistant's persona, scope, and behaviour in the **Instructions** field. This becomes the system prompt sent to the LLM at the start of every conversation.

    Use `{{variable}}` syntax to inject dynamic values at runtime — caller name, account ID, or any context passed when a call is initiated.
  </Step>

  <Step title="Add tools (optional)">
    <img alt="Add Tools" />

    Attach tools to extend what the assistant can do mid-conversation — query a knowledge base, call an external API, transfer the call, or end the session. Tools can also be added or modified after creation.
  </Step>

  <Step title="Name and create">
    <img alt="Success Confirmation" />

    Give the assistant a name and description, then click **Create Assistant**. The assistant is created at version `v1` in draft state. Configure voice, deployments, and advanced settings before going live.
  </Step>
</Steps>

<Note>
  A newly created assistant has no deployment attached. It will not handle live calls or web sessions until you configure at least one deployment under **Configure assistant → Deployments**.
</Note>

## Next best steps

<CardGroup>
  <Card title="Prompt templating" icon="file-code" href="/assistants/prompt-templating">
    Add runtime variables (`{{ args.* }}`, `{{ message.* }}`, `{{ system.* }}`) so one prompt works across many customer contexts.
  </Card>

  <Card title="Create new version" icon="git-branch" href="/assistants/create-new-version">
    Make changes safely in draft, test, and release explicitly without impacting live traffic.
  </Card>
</CardGroup>

***

## Configure your assistant

After creation, open **Configure assistant** from the top-right of the assistant page. Configuration is organized into six areas:

<CardGroup>
  <Card title="Prompt & Model" icon="cpu">
    System prompt, model selection, temperature, token limits, and advanced LLM parameters.
  </Card>

  <Card title="Configuration" icon="sliders-horizontal" href="/assistants/configuration/experience">
    Experience, Listen, and Speak settings for runtime behavior, speech input, and spoken output.
  </Card>

  <Card title="Knowledge & Retrieval" icon="book-open">
    Attach knowledge bases, set retrieval method (hybrid, semantic, text), top-K, score threshold, and reranking.
  </Card>

  <Card title="Tools" icon="zap">
    Knowledge retrieval, API request, endpoint invocation, call transfer, call hold, and end-of-conversation tool types.
  </Card>

  <Card title="Deployments" icon="phone">
    Phone, web widget, web app, WhatsApp, and API deployment channels — each with its own voice and experience settings.
  </Card>

  <Card title="Webhooks & Analysis" icon="activity">
    Post-call webhooks to downstream systems and analysis pipelines for conversation scoring and custom metrics.
  </Card>
</CardGroup>

***

### Prompt and model

The prompt and model configuration defines what your assistant knows, how it reasons, and how it generates responses.

#### System prompt

The system prompt is your primary control surface. It sets the assistant's persona, scope of knowledge, constraints, and tone. Well-written prompts are the single biggest lever for assistant quality.

<Tip>
  **For voice:** Keep sentences short and natural. Avoid bullet lists, markdown, and symbols — the TTS engine reads punctuation literally. Write instructions the way you'd brief a call centre agent.
</Tip>

**Dynamic variables** — inject runtime context into your prompt using `{{variable_name}}` syntax. Variables are automatically detected from your prompt and can be populated via the SDK when initiating a call:

```
You are an assistant for {{company_name}}. The caller's name is {{caller_name}}.
Their account tier is {{account_tier}}. Always address them by first name.
```

**Multi-turn prompt structure** — the prompt editor supports system, user, and assistant roles. Add example exchanges to shape the tone and structure of responses without increasing latency.

#### LLM model parameters

<AccordionGroup>
  <Accordion title="OpenAI / Azure OpenAI parameters">
    | Parameter             | Default  | Range                              | Notes                                               |
    | --------------------- | -------- | ---------------------------------- | --------------------------------------------------- |
    | Model                 | `gpt-4o` | —                                  | gpt-4, gpt-4o, gpt-4.1-mini, o3, o4-mini, and more  |
    | Temperature           | `0.7`    | 0–2                                | Higher = more creative, lower = more deterministic  |
    | Top P                 | `1`      | 0–1                                | Nucleus sampling; use with temperature, not instead |
    | Max completion tokens | `2048`   | ≥1                                 | Caps response length                                |
    | Frequency penalty     | `0`      | -2 to 2                            | Reduces word repetition                             |
    | Presence penalty      | `0`      | -2 to 2                            | Encourages topic diversity                          |
    | Stop sequences        | —        | up to 4                            | Tokens that halt generation                         |
    | Tool choice           | `auto`   | none / auto / required             | Control when tools are called                       |
    | Reasoning effort      | —        | low / medium / high                | For o-series models only                            |
    | Response format       | —        | text / json\_object / json\_schema | For structured output use cases                     |
  </Accordion>

  <Accordion title="Anthropic parameters">
    | Parameter         | Default         | Range       | Notes                                   |
    | ----------------- | --------------- | ----------- | --------------------------------------- |
    | Model             | `claude-opus-4` | —           | Opus 4, Sonnet 4, Sonnet 3.7, Haiku 3.5 |
    | Max tokens        | `1028`          | ≥1          | Caps response length                    |
    | Temperature       | `1.0`           | 0–1         | —                                       |
    | Top P             | —               | 0–1         | Nucleus sampling                        |
    | Top K             | —               | —           | Top-K sampling                          |
    | Stop sequences    | —               | —           | Halt generation tokens                  |
    | Extended thinking | —               | JSON config | Claude's built-in reasoning mode        |
  </Accordion>

  <Accordion title="AgentKit — custom LLM backend">
    AgentKit replaces the built-in LLM with your own gRPC server. Rapida streams user speech transcripts to your server and synthesizes your text responses to audio in real time.

    | Parameter       | Notes                                                                 |
    | --------------- | --------------------------------------------------------------------- |
    | Server URL      | `host:port` of your gRPC service (e.g. `my-server.example.com:50051`) |
    | TLS certificate | Optional — path to CA cert for mutual TLS                             |
    | Metadata        | Key-value map passed as gRPC metadata headers                         |

    Your server receives a bidirectional `Talk` stream. Rapida handles all audio — VAD, STT, TTS, telephony. Your server only handles text in / text out.

    See the [AgentKit guide](/assistants/agentkit) for implementation examples with LangChain, CrewAI, and Anthropic Claude.
  </Accordion>
</AccordionGroup>

#### Runtime model overrides

Outbound phone calls can override model provider options for a single conversation through `CreatePhoneCallRequest.options`. Pass the same option keys used by the assistant provider model, plus the connection keys below when you need to route a call to a different credential or model endpoint.

```json theme={null}
{
  "options": {
    "model.name": "gpt-4o-mini",
    "model.temperature": 0.2,
    "model.credential_id": "2230142097179373568",
    "model.connection.transport": "chat_complete",
    "model.connection.endpoint": "/v1/chat/completions"
  }
}
```

| Option key                                        | Type                | Description                                                                                                                 |
| ------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `model.name` and provider-specific `model.*` keys | varies              | Override the saved model provider options for this call, such as model name, temperature, token limits, or response format. |
| `model.credential_id`                             | `string` / `number` | Use a different saved provider credential for this call.                                                                    |
| `model.connection.transport`                      | `string`            | Override the model connection transport.                                                                                    |
| `model.connection.endpoint`                       | `string`            | Override the model connection endpoint.                                                                                     |

<Warning>
  Use model runtime overrides for controlled routing, testing, or tenant-specific credentials. Invalid model credentials or connection settings can prevent the call from starting.
</Warning>

***

### Configuration

Configuration controls the runtime behavior of each deployment: how a session starts, how user audio is captured and transcribed, and how assistant responses are spoken back. These settings directly affect latency, accuracy, and caller experience.

#### Listen — STT, VAD, EOS, and noise processing

<Tip>
  For telephone deployments (8kHz audio), choose STT providers with dedicated telephony models: Deepgram `nova-3`, Azure Speech (telephony mode), or AssemblyAI. For high-fidelity web audio (16kHz+), all providers perform well.
</Tip>

**STT providers:** Deepgram, AssemblyAI, Azure Cognitive Speech, Google Speech, OpenAI Whisper, Cartesia, Sarvam AI

| Audio setting      | Default    | Range              | What it controls                                                |
| ------------------ | ---------- | ------------------ | --------------------------------------------------------------- |
| STT language       | `multi`    | Provider-dependent | Primary transcription language; `multi` enables auto-detection  |
| STT model          | `nova-3`   | Provider-dependent | Accuracy vs. latency tradeoff per provider                      |
| Noise cancellation | `rn_noise` | —                  | RNNoise background noise suppression applied before VAD and STT |
| EOS backoff        | `2`        | 0–5                | Re-prompts ("Are you there?") before ending session on silence  |

**Voice Activity Detection (VAD)** — determines when the caller is speaking. Three providers available: [Silero VAD](/assistants/voice-activity-detection#silero-vad) (default, best general-purpose), [TEN VAD](/assistants/voice-activity-detection#ten-vad) (lowest latency), and [FireRed VAD](/assistants/voice-activity-detection#firered-vad) (best noise robustness). See [Voice Activity Detection](/assistants/voice-activity-detection) for provider details, parameters, and tuning guidance.

**End of Speech (EOS)** — determines when the caller has finished their turn. Three providers available: [Silence-Based](/assistants/end-of-speech#silence-based-eos) (default, simple fixed timeout), [Pipecat Smart Turn](/assistants/end-of-speech#pipecat-smart-turn-eos) (audio model, catches prosodic cues), and [LiveKit Turn Detector](/assistants/end-of-speech#livekit-turn-detector-eos) (language model with conversation history). See [End of Speech Detection](/assistants/end-of-speech) for provider details, parameters, and tuning guidance.

<Note>
  EOS is the most impactful latency lever after model selection. With Silence-Based EOS at 700ms, the assistant waits 0.7 seconds of silence before responding. Model-based providers (Pipecat, LiveKit) can reduce this wait by detecting turn completion before the full silence timeout expires — the assistant responds faster while cutting off callers less often.
</Note>

#### Speak — TTS and pronunciation

**TTS providers:** ElevenLabs, Cartesia, Deepgram Aura, OpenAI TTS, Azure Speech, Google Cloud TTS, PlayHT, Sarvam AI

| Speaker setting            | Default            | What it controls                                                                                                    |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Voice ID                   | Provider-dependent | The specific voice model. Supports cloned brand voices on ElevenLabs and Resemble                                   |
| Speed / emotion            | Normal             | Provider-specific; Cartesia exposes `slowest → fastest` and emotion controls (`anger:high`, `positivity:low`, etc.) |
| Sentence boundaries        | `.!?;:—…`          | Characters that flush a TTS chunk for immediate playback. Tuning these reduces time-to-first-audio                  |
| Conjunction break          | `240 ms`           | Pause inserted at conjunctions (and, but, or). Adds natural rhythm to long sentences                                |
| Pronunciation dictionaries | —                  | Normalize how abbreviations, currencies, dates, URLs, and technical terms are spoken                                |

<Tip>
  Add your product names, acronyms, and technical terms to the pronunciation dictionary to prevent the TTS engine from mispronouncing them. This is especially important for brand names and medical or legal terms.
</Tip>

***

### Knowledge and retrieval

Attach one or more knowledge bases to give your assistant access to documents, FAQs, product data, or any content indexed in Rapida.

| Setting          | Default  | Range                    | Notes                                                                                                                            |
| ---------------- | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Retrieval method | `hybrid` | hybrid / semantic / text | Hybrid combines vector similarity and full-text search — best default for most use cases                                         |
| Top K            | `5`      | 1–20                     | Number of document chunks retrieved per query. Higher = more context, higher latency                                             |
| Score threshold  | `0.5`    | 0–1                      | Minimum relevance score. Raise to reduce noise; lower to improve recall                                                          |
| Reranking        | `off`    | —                        | Cohere reranker re-scores retrieved chunks before passing to the LLM. Improves precision at the cost of a small latency increase |

See [Create a Knowledge Base](/knowledge/create-knowledge) for document ingestion, connector setup, and embedding model configuration.

***

### Tools

Tools extend what your assistant can do mid-conversation without breaking the voice flow. The LLM decides when to call a tool based on its description — write clear, specific descriptions.

<CardGroup>
  <Card title="Knowledge Retrieval" icon="book-open" href="/assistants/tools/add-knowledge-tool">
    Query a Rapida knowledge base in real time. Returns the most relevant document chunks to the LLM as context.
  </Card>

  <Card title="API Request" icon="zap" href="/assistants/tools/add-api-tool">
    Call any external HTTP endpoint mid-conversation — CRM lookups, inventory checks, booking APIs. Define the request schema and the LLM populates the parameters from conversation context.
  </Card>

  <Card title="Endpoint (LLM Call)" icon="cpu" href="/assistants/tools/add-endpoint-tool">
    Invoke a Rapida endpoint — a separately configured LLM prompt — for specialised sub-tasks: classification, extraction, or complex reasoning offloaded from the main conversation model.
  </Card>

  <Card title="Transfer Call" icon="phone-forwarded" href="/assistants/tools/add-transfer-call-tool">
    Hand an active phone call to a human agent, queue, department number, or SIP endpoint when the assistant should escalate the conversation.
  </Card>

  <Card title="Put On Hold" icon="phone" href="/assistants/tools/add-put-on-hold-tool">
    Pause the call and play hold music while a backend process completes — useful when a lookup or action takes longer than a voice turn allows.
  </Card>

  <Card title="End of Conversation" icon="phone-off" href="/assistants/tools/add-end-of-conversation-tool">
    Terminate the call programmatically when the assistant determines the conversation objective has been met.
  </Card>
</CardGroup>

<Note>
  Tool names must use only letters, numbers, and underscores (no spaces). The description is passed directly to the LLM — it determines when and whether the tool is called. Be specific: "Search the product knowledge base for pricing information" outperforms "Search knowledge base".
</Note>

***

### Conversation experience

These settings control the runtime behaviour of a live session — what happens when the caller goes silent, how long sessions last, and what the assistant says at the start of a call.

| Setting               | Default                                       | Range                | Notes                                                                                |
| --------------------- | --------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| Greeting message      | —                                             | —                    | Spoken immediately when a call connects. Supports `{{variable}}` for personalisation |
| Unclear input timeout | `0.5 s`                                       | 0.5–5 s              | Wait before asking the user to repeat unclear or interrupted input                   |
| Unclear input message | `I didn't catch that. Could you repeat that?` | Up to 250 characters | Spoken or shown when the assistant could not understand the user                     |
| Idle message          | `Are you there?`                              | —                    | Spoken after the idle timeout expires without user input                             |
| Idle silence timeout  | `30 s`                                        | 5–120 s              | Time before the idle message triggers                                                |
| Idle backoff          | `2`                                           | 0–5                  | How many times the idle message repeats before ending the session                    |
| Max session duration  | `300 s`                                       | 180–600 s (phone)    | Hard cap on session length — protects against runaway calls                          |
| Error message         | —                                             | —                    | Spoken when the assistant encounters an unrecoverable error                          |

***

### Webhooks and post-call analysis

**Webhooks** fire for call lifecycle events such as `call.received`, `call.ringing`, `call.started`, `call.hangup`, `call.ended`, `call.failed`, and `call.cancelled`; WebRTC media events such as `webrtc.connected`, `webrtc.audio_track_received`, `webrtc.reconnecting`, `webrtc.failed`, and `webrtc.disconnected`; and conversation lifecycle events such as `conversation.begin`, `conversation.resume`, `conversation.completed`, and `conversation.error`. Completed conversation webhooks include transcripts, metadata, metrics, and any successful post-call analysis output.

**Analysis pipelines** run before the `conversation.completed` webhook is recorded. They invoke a configured Rapida endpoint — typically an LLM prompt — against the conversation transcript to produce structured output: sentiment scores, intent labels, CSAT predictions, compliance flags, or any custom metric. Successful analysis output is added to webhook metadata as `analysis.<analysis_name>`.

See [Webhooks](/assistants/webhook/overview) and [Analysis](/assistants/analysis/overview) for full configuration details.

***

## Version control

Every change to your assistant's prompt, model, or parameters creates a new **version**. Versions let you safely iterate without affecting live traffic.

<Warning>
  New versions are **not deployed automatically**. After creating a version, it stays in draft state until you explicitly release it. Live deployments continue running the previously released version until you promote the new one.
</Warning>

| Action          | What it does                                                                |
| --------------- | --------------------------------------------------------------------------- |
| Create version  | Saves a new draft with updated prompt/model config and a change description |
| Release version | Promotes the version to live — all active deployments switch immediately    |
| Rollback        | Re-release a previous version to revert a bad change                        |

This model lets you run A/B tests, stage changes in a debugger deployment before pushing to phone, and maintain a full audit trail of every prompt change — who made it, when, and why.

***

## Next steps

<CardGroup>
  <Card title="Set up a phone deployment" icon="phone" href="/voice-deployment-options/phone">
    Connect a telephony provider and go live with inbound and outbound calling.
  </Card>

  <Card title="Add a knowledge base" icon="book-open" href="/knowledge/create-knowledge">
    Index documents, wikis, and data sources for retrieval during calls.
  </Card>

  <Card title="Configure webhooks" icon="activity" href="/assistants/webhook/overview">
    Stream call events and transcripts to external systems in real time.
  </Card>

  <Card title="Build a custom LLM backend" icon="cpu" href="/assistants/agentkit">
    Use AgentKit to plug your own reasoning engine into Rapida's audio pipeline.
  </Card>
</CardGroup>


# Provider Model (Prompt Executor)
Source: https://doc.rapida.ai/assistants/create-new-version

Step-by-step guide to creating a new version of an existing AI assistant

This guide walks you through the process of creating a new version of an existing assistant in the platform.

<Steps>
  <Step title="Navigate to Assistant Overview">
    <img alt="Navigate to Assistant Overview" />

    Begin by navigating to the overview page of the assistant you want to update.
  </Step>

  <Step title="Initiate New Version Creation">
    Click on the "Create new version" button to start the process of creating a new version of your assistant.
  </Step>

  <Step title="Update Assistant">
    <img alt="Update Assistant" />

    In the "Update Assistant" step:

    * You can modify the assistant's definition, including the model, instructions, and variables.
    * The current example shows using the GPT-4v model.
    * The system prompt defines the assistant's role, in this case as a minimal therapist.
    * You can add or modify arguments, such as the `user_name` variable shown.
  </Step>

  <Step title="Change Definition">
    <img alt="Change Definition" />

    In the "Change Definition" step:

    * Provide a change description that summarizes what's been updated in this version.
    * The example shows a simple description: "Change assistant version on 2023-08-22"
    * Note the warning that new versions will not be deployed automatically and manual deployment is required to update the production version.
  </Step>

  <Step title="Review and Create">
    After reviewing your changes, click the "Create new version" button to finalize the creation of the new assistant version.
  </Step>

  <Step title="Version History">
    <img alt="Version History" />

    After creating a new version:

    * You can view the version history of your assistant.
    * The history shows different versions, including which one is currently in use.
    * Each version has a unique identifier and shows when it was last updated.
  </Step>
</Steps>

Remember that creating a new version allows you to make changes and test them before deploying to production. This helps maintain a stable production environment while allowing for continuous improvement of your assistant.


# End of Speech Detection (EOS)
Source: https://doc.rapida.ai/assistants/end-of-speech

Understand End of Speech providers, their parameters, and how to choose the right one for your voice AI assistant.

End of Speech (EOS) detection determines **when a caller has finished their turn** and the assistant should start responding. It is the single most impactful setting for perceived conversation latency — a fast EOS means the assistant responds quickly, but a premature EOS means the assistant cuts the caller off mid-sentence.

EOS works downstream of VAD. While VAD detects whether the caller is actively making sound (frame-by-frame), EOS decides whether a period of silence means "I'm done talking" or "I'm pausing to think".

<Warning>
  **Deprecation notice:** LiveKit Turn Detector EOS is being disabled and will be deprecated due to a licensing issue. Do not use it for new assistants.
</Warning>

```mermaid theme={null}
flowchart LR
    A["VAD\nSpeech activity"] --> B["STT\nTranscription"]
    B --> C["EOS\nTurn boundary detection"]
    C -->|Turn complete| D["LLM\nGenerate response"]
    C -->|Still speaking| E["Wait for more speech"]
```

***

## Providers

Rapida supports three EOS providers, ranging from a simple silence timer to ML-powered turn detection models.

| Provider                                                | Description                                                                                                  |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **[Silence-Based](#silence-based-eos)**                 | Fixed silence timeout. Simple, reliable, zero compute overhead. The default.                                 |
| **[Pipecat Smart Turn](#pipecat-smart-turn-eos)**       | Whisper-based audio model (\~8 MB). Predicts turn completion directly from speech audio.                     |
| **[LiveKit Turn Detector](#livekit-turn-detector-eos)** | Language model that predicts turn completion from transcribed text. Context-aware with conversation history. |

***

## Silence-Based EOS

The simplest approach: after the last speech activity, wait for a fixed duration of silence, then trigger end-of-speech. No ML model, no inference overhead.

**Why choose Silence-Based:**

* Zero additional compute — no model to load or run
* Predictable, deterministic behaviour — the timeout is exactly what you configure
* Works with any language, any accent, any audio quality
* Easiest to reason about and debug

**When to use:** Most deployments, especially when starting out. Silence-based EOS is the default and works well for the majority of voice AI use cases. It is the right choice when you want simplicity and predictability, or when your callers speak in short, clear turns (IVR menus, yes/no questions, appointment booking).

**When it falls short:** Callers who pause mid-sentence (e.g., "I'd like to book a flight to... hmm... London") will be interrupted if the pause exceeds the timeout. This is where model-based EOS providers add value.

### Parameters

| Parameter        | Config Key               | Default   | Range         | Description                                                                         |
| ---------------- | ------------------------ | --------- | ------------- | ----------------------------------------------------------------------------------- |
| Activity Timeout | `microphone.eos.timeout` | `1000 ms` | 500 – 4000 ms | Duration of silence after the last speech activity before triggering end-of-speech. |

<Tip>
  **Timeout tuning guide:**

  * **500 – 600 ms** — Very fast. The assistant responds almost immediately when the caller pauses. Best for IVR-style interactions with short, predictable answers ("yes", "no", "option 2"). Callers will be cut off if they pause to think.
  * **700 – 800 ms** — Fast and balanced. Good default for most conversational assistants. Short enough to feel responsive, long enough for typical sentence-internal pauses.
  * **1000 – 1500 ms** — Relaxed. Gives callers time to pause and continue. Good for complex conversations where callers need to recall information (account numbers, addresses, medical details).
  * **2000 – 4000 ms** — Very patient. Use for elderly callers, non-native speakers, or scenarios where callers frequently pause mid-thought. Increases perceived latency significantly.
</Tip>

<Note>
  The default when switching to Silence-Based EOS in the UI is **700 ms**. The backend default (when no value is set) is **1000 ms**. The 700 ms UI default is optimized for a balance between responsiveness and natural conversation flow.
</Note>

***

## Pipecat Smart Turn EOS

[Pipecat Smart Turn](https://github.com/pipecat-ai/smart-turn) uses a Whisper-based audio model (\~8 MB) to predict whether the caller has finished their turn directly from the speech audio waveform. Unlike silence-based detection, it understands prosodic cues — falling intonation, slowing speech rate, and other acoustic signals that indicate turn completion.

**Why choose Pipecat Smart Turn:**

* Detects turn completion from **audio features**, not just silence — catches prosodic cues like falling intonation at the end of a sentence
* \~10 ms inference time per prediction — negligible latency impact
* Supports 23 languages out of the box
* Small model size (\~8 MB ONNX)
* Uses a rolling audio buffer (\~5 seconds) for context — doesn't need the full conversation history

**When to use:** Conversations where callers frequently pause mid-sentence. Pipecat Smart Turn significantly reduces premature turn-taking compared to silence-based detection because it can distinguish between a "thinking pause" (flat or rising intonation) and a "finished speaking" pause (falling intonation, complete sentence prosody).

Best for: customer support, complex information gathering (addresses, travel bookings), multilingual deployments where pause patterns vary by language.

**How it works:**

1. Audio from the caller is accumulated in a rolling buffer (max \~5 seconds at 16 kHz)
2. When a final STT transcript arrives, the model runs inference on the buffered audio
3. The model outputs a probability between 0 and 1 indicating likelihood of turn completion
4. If probability >= threshold → use `quick_timeout` (short wait, then fire)
5. If probability \< threshold → use `silence_timeout` (long wait, keep listening)
6. Interim STT transcripts reset the timer with the `fallback_timeout`

### Parameters

| Parameter                 | Config Key                       | Default   | Range         | Description                                                                                                                                                                  |
| ------------------------- | -------------------------------- | --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Turn Completion Threshold | `microphone.eos.threshold`       | `0.5`     | 0.1 – 0.9     | Probability threshold for turn completion. When the model's prediction exceeds this value, it considers the turn complete and uses the quick timeout.                        |
| Quick Timeout             | `microphone.eos.quick_timeout`   | `200 ms`  | 50 – 1000 ms  | Short silence buffer after the model predicts "turn complete". Gives the caller a brief window to correct themselves ("yes... actually wait") before the assistant responds. |
| Extended Timeout          | `microphone.eos.silence_timeout` | `2000 ms` | 500 – 5000 ms | Silence duration used when the model predicts the caller is still speaking. Acts as a long patience window for mid-thought pauses.                                           |
| Fallback Timeout          | `microphone.eos.timeout`         | `500 ms`  | 500 – 4000 ms | Silence timeout used for interim STT transcripts and when model inference fails. Falls back to simple silence-based behaviour.                                               |

<AccordionGroup>
  <Accordion title="Parameter tuning recommendations">
    **Turn Completion Threshold (0.1 – 0.9)**

    | Range     | Behaviour                                                                                                                  |
    | --------- | -------------------------------------------------------------------------------------------------------------------------- |
    | 0.1 – 0.3 | Aggressive. The model triggers on weak signals. Faster responses but more false triggers. Good for IVR-style interactions. |
    | 0.4 – 0.6 | Balanced. Default is 0.5. The model needs moderate confidence before triggering. Best for general-purpose conversations.   |
    | 0.7 – 0.9 | Conservative. Only strong turn-completion signals trigger. Use when false interruptions are very costly (legal, medical).  |

    **Quick Timeout (50 – 1000 ms)**

    | Range         | Behaviour                                                                         |
    | ------------- | --------------------------------------------------------------------------------- |
    | 50 – 150 ms   | Almost instant response after model says "done". Snappy but no correction window. |
    | 200 – 300 ms  | Default range. Brief correction window. Good balance.                             |
    | 500 – 1000 ms | Long correction window. Use if callers frequently say "wait" or "actually".       |

    **Extended Timeout (500 – 5000 ms)**

    | Range          | Behaviour                                                                       |
    | -------------- | ------------------------------------------------------------------------------- |
    | 500 – 1000 ms  | Short patience. If the model keeps saying "not done", force EOS quickly anyway. |
    | 2000 ms        | Default. Gives callers 2 seconds to continue after a pause.                     |
    | 3000 – 5000 ms | Very patient. For callers who take long pauses mid-thought.                     |
  </Accordion>
</AccordionGroup>

***

## LiveKit Turn Detector EOS

The [LiveKit Turn Detector](https://github.com/livekit/turn-detector) uses a language model to predict turn completion from **transcribed text** combined with **conversation history**. Unlike Pipecat (which analyzes audio), LiveKit analyzes the linguistic content of what was said to determine if the caller is done.

**Why choose LiveKit Turn Detector:**

* **Context-aware** — uses conversation history (up to 6 turns by default) to make better predictions. If the assistant asked "What is your address?", the model knows the caller is likely still speaking during a pause after saying "123 Main Street"
* **Text-based analysis** — catches semantic cues that audio models miss. For example, "My address is 123" is clearly incomplete, regardless of intonation
* **Reduces false triggers** on addresses, phone numbers, and lists — the model understands that these naturally contain pauses between segments
* Available in two model variants: English-only (66 MB, optimized) and Multilingual (378 MB, 14 languages)

**When to use:** Conversations with structured data collection where callers frequently pause mid-answer. The LiveKit model excels at preventing premature turn-taking during:

* Address dictation ("123 Main Street... apartment 4B... New York")
* Phone numbers ("area code 212... 555... 1234")
* Lists or multi-part answers
* Complex questions requiring thought

**How it works:**

1. Final STT transcripts are accumulated into the current user turn
2. When a final transcript arrives, the model builds a chat template from conversation history + current text
3. The model predicts an end-of-utterance probability
4. If probability >= threshold → use `quick_timeout`
5. If probability \< threshold → use `silence_timeout`
6. Assistant responses (from `LLMResponseDonePacket`) are recorded in history for context

### Parameters

| Parameter                 | Config Key                       | Default   | Range                | Description                                                                                                                                                                                                                                                 |
| ------------------------- | -------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model                     | `microphone.eos.model`           | `en`      | `en`, `multilingual` | Model variant. `en` is 66 MB and optimized for English. `multilingual` is 378 MB and supports Chinese, German, Dutch, English, Portuguese, Spanish, French, Italian, Japanese, Korean, Russian, Turkish, Indonesian, and Hindi.                             |
| Turn Completion Threshold | `microphone.eos.threshold`       | `0.0289`  | 0.001 – 0.1          | Probability threshold for turn completion. This value is much lower than Pipecat's threshold because the LiveKit model outputs probabilities on a different scale. The default `0.0289` is the "unlikely threshold" from LiveKit's reference configuration. |
| Quick Timeout             | `microphone.eos.quick_timeout`   | `250 ms`  | 50 – 500 ms          | Short buffer after model says "done" before firing EOS. Catches fast corrections.                                                                                                                                                                           |
| Safety Timeout            | `microphone.eos.silence_timeout` | `1500 ms` | 500 – 5000 ms        | Maximum silence before forcing EOS when the model keeps predicting "not done". Acts as a safety fallback to prevent indefinite waiting.                                                                                                                     |
| Fallback Timeout          | `microphone.eos.timeout`         | `500 ms`  | 300 – 2000 ms        | Silence timeout for interim transcripts and model inference failures.                                                                                                                                                                                       |

<Warning>
  The LiveKit threshold range (0.001 – 0.1) is very different from Pipecat's (0.1 – 0.9). Do not copy threshold values between providers — they use fundamentally different models with different probability distributions.
</Warning>

<AccordionGroup>
  <Accordion title="Model selection guide">
    **English model (`en`, 66 MB)**

    | Aspect       | Detail                                                                                                                              |
    | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
    | Optimisation | Faster inference, smaller memory footprint                                                                                          |
    | Accuracy     | Better for English conversations than the multilingual model                                                                        |
    | When to use  | Your callers speak English, even with accents (the STT provider handles accent recognition; LiveKit only sees the transcribed text) |

    **Multilingual model (`multilingual`, 378 MB)**

    | Aspect      | Detail                                                                                                                                                                                             |
    | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Languages   | Chinese (zh), German (de), Dutch (nl), English (en), Portuguese (pt), Spanish (es), French (fr), Italian (it), Japanese (ja), Korean (ko), Russian (ru), Turkish (tr), Indonesian (id), Hindi (hi) |
    | Init time   | Takes longer to load at session start (\~100–200 ms extra)                                                                                                                                         |
    | When to use | Your callers speak non-English languages or you handle mixed-language conversations                                                                                                                |
  </Accordion>

  <Accordion title="Parameter tuning recommendations">
    **Threshold (0.001 – 0.1)**

    | Value       | Behaviour                                                                                                                   |
    | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
    | 0.01 – 0.02 | Conservative. The model needs high confidence to trigger. Fewer false interruptions but slower response.                    |
    | 0.0289      | Default. Matches LiveKit's "unlikely threshold" — a good balance between responsiveness and accuracy.                       |
    | 0.05 – 0.1  | Aggressive. Triggers on weaker signals. Faster responses but more false turns, especially during pauses in structured data. |

    **Safety Timeout (500 – 5000 ms)**

    | Range          | Behaviour                                                                                                           |
    | -------------- | ------------------------------------------------------------------------------------------------------------------- |
    | 500 – 1000 ms  | Short safety net. If the model keeps saying "not done" for 1 second, fire anyway. Use for fast-paced conversations. |
    | 1500 ms        | Default. Good balance.                                                                                              |
    | 3000 – 5000 ms | Very patient. The model gets a long time to keep predicting. Use when callers dictate very long multi-part answers. |
  </Accordion>
</AccordionGroup>

***

## Choosing a provider

| Criteria                        | Silence-Based           | Pipecat Smart Turn     | LiveKit Turn Detector                           |
| ------------------------------- | ----------------------- | ---------------------- | ----------------------------------------------- |
| **Approach**                    | Fixed silence timer     | Audio model (prosody)  | Language model (text + history)                 |
| **Model size**                  | None                    | \~8 MB ONNX            | 66 MB (en) / 378 MB (multilingual)              |
| **Init time**                   | Instant                 | \~20–50 ms             | \~50–200 ms                                     |
| **Inference time**              | None                    | \~10 ms per prediction | \~5–15 ms per prediction                        |
| **Context used**                | Silence duration only   | Last \~5s of audio     | Transcribed text + conversation history         |
| **Languages**                   | All (language-agnostic) | 23 languages           | English or 14 languages                         |
| **Handles mid-sentence pauses** | No                      | Yes (prosodic cues)    | Yes (semantic understanding)                    |
| **Handles structured data**     | No                      | Partially              | Yes (understands incomplete addresses, numbers) |
| **Compute overhead**            | Zero                    | Low                    | Moderate                                        |

### Decision guide

<Steps>
  <Step title="Start with Silence-Based">
    For most new assistants, Silence-Based EOS with a 700 ms timeout is the right starting point. It's simple, predictable, and works well for 80% of use cases.
  </Step>

  <Step title="Switch to Pipecat if callers get cut off">
    If your conversation logs show frequent premature turn-taking — callers being interrupted mid-sentence during natural pauses — switch to Pipecat Smart Turn. Its audio model catches prosodic cues that silence timers miss.
  </Step>

  <Step title="Switch to LiveKit for structured data collection">
    If your assistant collects addresses, phone numbers, or multi-part answers where callers naturally pause between segments, LiveKit's text-based model with conversation history is the strongest choice. It understands that "123 Main Street" after "What is your address?" is likely incomplete.
  </Step>
</Steps>

<Tip>
  You can combine any EOS provider with any VAD provider. They are independent components in Listen configuration. A common high-quality configuration is **Silero VAD + LiveKit EOS** or **Silero VAD + Pipecat Smart Turn EOS**.
</Tip>

***

## How EOS providers interact with VAD

VAD and EOS work together but serve different purposes:

| Stage               | VAD                                     | EOS                                                  |
| ------------------- | --------------------------------------- | ---------------------------------------------------- |
| **What it detects** | "Is the caller making sound right now?" | "Has the caller finished their complete thought?"    |
| **Granularity**     | Frame-by-frame (every 10–16 ms)         | Per-utterance (after each STT transcript)            |
| **Output**          | Speech onset/offset events              | End-of-speech signal that triggers LLM response      |
| **Affected by**     | Audio signal quality, background noise  | Pause patterns, speech content, conversation context |

VAD sends speech start and end events. EOS uses VAD start to block premature completion while speech is active, and VAD end to flush a pending final transcript when one exists. Interim STT resets the EOS timer while more transcript text is still arriving.

For the model-based EOS providers (Pipecat and LiveKit), the EOS also receives the final STT transcript. On receiving a final transcript, the model runs inference to decide whether to use the quick timeout (turn complete) or extended timeout (still speaking).

***

## Next steps

<CardGroup>
  <Card title="Voice Activity Detection" icon="shield" href="/assistants/voice-activity-detection">
    Configure VAD providers and understand speech detection parameters.
  </Card>

  <Card title="Create an Assistant" icon="plus" href="/assistants/create-assistant">
    Set up EOS as part of Listen configuration.
  </Card>
</CardGroup>


# Tools
Source: https://doc.rapida.ai/assistants/introduction-to-tools

Enhance your assistant with knowledge retrieval, API calls, endpoint calls, call transfer, call hold, and conversation-ending actions.

Tools let your assistant take actions during a conversation. The assistant decides when to call a tool from the tool name, description, and argument schema you configure.

## Available tools

<CardGroup>
  <Card title="Knowledge Retrieval" icon="book-open" href="/assistants/tools/add-knowledge-tool">
    Query a Rapida knowledge base and return relevant document chunks to the assistant.
  </Card>

  <Card title="API Request" icon="zap" href="/assistants/tools/add-api-tool">
    Call an external HTTP API for CRM lookups, booking flows, inventory checks, and other backend actions.
  </Card>

  <Card title="Endpoint (LLM Call)" icon="cpu" href="/assistants/tools/add-endpoint-tool">
    Invoke a separate Rapida endpoint for specialized prompt, classification, extraction, or reasoning tasks.
  </Card>

  <Card title="Transfer Call" icon="phone-forwarded" href="/assistants/tools/add-transfer-call-tool">
    Hand an active phone call to a human agent, queue, phone number, or SIP target.
  </Card>

  <Card title="Put On Hold" icon="phone" href="/assistants/tools/add-put-on-hold-tool">
    Pause the conversation while a longer-running lookup or backend action completes.
  </Card>

  <Card title="End of Conversation" icon="phone-off" href="/assistants/tools/add-end-of-conversation-tool">
    End the session when the assistant determines the conversation is complete.
  </Card>
</CardGroup>

<Note>
  Tool names must use only letters, numbers, and underscores. Write descriptions that tell the model exactly when to call the tool and what information to collect first.
</Note>

## How tools run

Most tools follow the same runtime flow:

1. The assistant selects a tool based on the conversation and the tool description.
2. The assistant fills the tool fields from conversation context.
3. Rapida executes the configured action or sends the channel-level directive.
4. The tool result is recorded in conversation logs and used by the assistant when the conversation continues.

Call-control tools such as [Transfer Call](/assistants/tools/add-transfer-call-tool) and [End of Conversation](/assistants/tools/add-end-of-conversation-tool) can end or redirect the active call instead of returning data to the model.


# Adding Knowledge Sources
Source: https://doc.rapida.ai/assistants/knowledge/add-knowledge

Configure knowledge sources for your assistant to enhance information retrieval

This guide explains how to configure knowledge sources for your assistant, enabling it to access and utilize external information more effectively.

## Prerequisites

Before you begin, ensure you have:

<CardGroup>
  <Card title="Created a Knowledge Source" icon="book" href="/knowledge/create-knowledge">
    Learn how to create a knowledge source in our guide.
  </Card>

  <Card title="Created an Assistant" icon="bot" href="/assistants/create-assistant">
    If you haven't created an assistant yet, follow our creating an assistant
    guide.
  </Card>
</CardGroup>

<Steps>
  <Step title="Access Knowledge Configuration">
    When creating or editing an assistant, navigate to the "Manage" tab and select "Knowledges" from the sidebar.
  </Step>

  <Step title="Create or Select Knowledge Source">
    <img alt="Configure Retrieval Settings" /> In
    the "Knowledge" field, you can: - Type to search for an existing knowledge
    source - Select from the dropdown list of available knowledge sources - Create
    a new knowledge source if needed
  </Step>

  <Step title="Configure Retrieval Settings">
    <img alt="Configure Retrieval Settings" />

    1. **Choose the search method:**

       * **Hybrid Search (recommended)**: Combines full-text search and vector search for optimal results.
       * **Semantic Search**: Uses query embeddings to find semantically similar content.
       * **Full Text Search**: Indexes and searches all terms in the document.

    2. **Adjust the "Top K" value**: This determines the number of most relevant results to retrieve. A higher value may provide more comprehensive results but could include less relevant information.

    3. **Set the "Score Threshold"**: This filters results based on their relevance score. A higher threshold will only return more closely matched results.

    4. **Enable "Reranking" (Optional)**: Reranking improves the relevance of retrieved information by re-evaluating the initial search results, considering additional context and nuances, and potentially reordering the results for better relevance.

    5. **Select the reranking model**: If reranking is enabled, choose an appropriate model. The default "Rerank English v2.0" works well for English content.
  </Step>

  <Step title="Confirm Knowledge Configuration">
    After configuring the knowledge settings, click "Connect knowledge" to add it to your assistant.

    You can add multiple knowledge sources by repeating this process, allowing your assistant to access a diverse range of information.
  </Step>
</Steps>

## Best Practices

* Start with Hybrid Search for a balance of broad coverage and semantic understanding.
* Experiment with different "Top K" and "Score Threshold" values to find the optimal balance for your use case.
* Enable reranking for more nuanced and contextually relevant results, especially for complex queries.

By carefully configuring these settings, you can significantly enhance your assistant's ability to retrieve and utilize knowledge effectively.


# Noise cancellation
Source: https://doc.rapida.ai/assistants/noise-cancellation

Configure background noise removal and understand how it affects VAD, STT, and voice assistant latency.

Noise cancellation removes background audio before Rapida runs Voice Activity Detection and Speech-to-Text. It helps prevent false speech detection and improves transcription quality when users speak from phones, shared offices, vehicles, cafes, or other noisy environments.

```mermaid theme={null}
flowchart LR
    A["User audio"] --> B["Noise cancellation"]
    B --> C["Voice Activity Detection"]
    C --> D["Speech-to-Text"]
```

<Info>
  Noise cancellation is configured in **Voice Input** under **Show advanced settings**. It is part of the deployment voice configuration, so each deployment can use its own setting.
</Info>

## Provider

Rapida exposes **RNNoise** as the standard noise cancellation provider.

RNNoise is designed for real-time speech enhancement. It reduces steady background noise while preserving speech intelligibility, making it a good default for phone calls and browser microphone sessions.

| Provider | Best for                                                        | Notes                                      |
| -------- | --------------------------------------------------------------- | ------------------------------------------ |
| RNNoise  | Phone calls, office noise, keyboard noise, light traffic, cafes | Default choice for most voice deployments. |

## When to use it

Enable noise cancellation when:

* Calls happen over PSTN or mobile networks.
* Users may be in offices, stores, vehicles, cafes, or shared spaces.
* VAD triggers on background audio.
* STT receives noisy audio and produces unstable transcripts.
* You want one safer default across many caller environments.

You may disable or avoid it when:

* Audio is already clean studio-quality input.
* Another upstream system already performs strong noise suppression.
* You hear speech artifacts after enabling it.
* The STT provider performs better with untouched audio in your test calls.

<Warning>
  Do not use noise cancellation to hide poor microphone placement, severe clipping, or echo. It can reduce background noise, but it cannot recover speech that was not captured clearly.
</Warning>

## How it affects the pipeline

| Component | Effect                                                             |
| --------- | ------------------------------------------------------------------ |
| VAD       | Cleaner audio reduces false speech starts from background noise.   |
| STT       | Cleaner speech can improve transcript stability and word accuracy. |
| EOS       | Better VAD start/end signals make turn detection more predictable. |
| TTS       | No direct effect. TTS happens after the assistant generates text.  |

## Tuning with VAD

Noise cancellation and VAD should be tuned together.

| Symptom                                      | What to adjust                                            |
| -------------------------------------------- | --------------------------------------------------------- |
| Background noise interrupts assistant speech | Keep RNNoise enabled and raise VAD confidence.            |
| Quiet speakers are missed                    | Keep RNNoise enabled, then lower VAD confidence slightly. |
| Words are clipped at the start               | Lower VAD confidence or reduce VAD start seconds.         |
| Speech gets split into multiple chunks       | Increase VAD stop seconds.                                |

See [Voice Activity Detection](/assistants/voice-activity-detection) for VAD provider and confidence/start/stop tuning details.

## Channel guidance

| Channel       | Recommendation                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Phone Call    | Enable RNNoise by default. Phone audio is often compressed, narrowband, and noisy.                                                    |
| Web Widget    | Enable RNNoise when users may speak from uncontrolled environments.                                                                   |
| Web App / SDK | Enable RNNoise for support, sales, healthcare, field, or accessibility workflows. Test clean in-app microphone flows before deciding. |

## Troubleshooting

| Symptom                                        | Likely cause                                             | What to do                                                           |
| ---------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| Transcript includes background words or sounds | Noise cancellation off or VAD too sensitive              | Enable RNNoise and raise VAD confidence.                             |
| User speech sounds processed or thin           | Noise suppression too aggressive for the input           | Test with RNNoise disabled for clean microphones.                    |
| Assistant still interrupts on noise            | VAD confidence too low                                   | Raise VAD confidence after enabling RNNoise.                         |
| STT accuracy is still poor                     | Wrong language/model, bad input audio, or clipped speech | Check [Speech-to-Text](/assistants/speech-to-text) and VAD settings. |

## Related

<CardGroup>
  <Card title="Listen" icon="mic" href="/assistants/configuration/listen">
    Understand where noise cancellation sits in speech input configuration.
  </Card>

  <Card title="Voice Activity Detection" icon="activity" href="/assistants/voice-activity-detection">
    Tune speech detection after noise cancellation.
  </Card>

  <Card title="Speech-to-Text" icon="mic" href="/assistants/speech-to-text">
    Choose the transcription provider and model.
  </Card>

  <Card title="End of Speech Detection" icon="clock" href="/assistants/end-of-speech">
    Tune turn completion after VAD and STT.
  </Card>
</CardGroup>


# Assistants
Source: https://doc.rapida.ai/assistants/overview

Understand what an assistant is, how it is structured, how a live conversation flows through it, and how to iterate safely in production.

An **assistant** is the core unit of Rapida. It packages everything needed to run a production voice AI conversation — the LLM and prompt, experience settings, listen/speak configuration, knowledge sources, tools, and deployment channels — into a single versioned object.

One assistant configuration drives every channel. The same prompt, model, and voice settings that handle your inbound phone calls also power your web widget and WhatsApp deployment. Change something once and it propagates everywhere.

<Info>
  Assistants are **version-controlled**. Every prompt or model change creates a new draft version. Versions must be explicitly released — live deployments are never changed automatically.
</Info>

## Anatomy of an assistant

<CardGroup>
  <Card title="Prompt & Model" icon="cpu">
    Define persona and behavior with a system prompt, then choose and tune the LLM model per version.
  </Card>

  <Card title="Configuration" icon="sliders-horizontal" href="/assistants/configuration/experience">
    Tune experience, [Listen](/assistants/configuration/listen), and [Speak](/assistants/configuration/speak) settings per deployment channel.
  </Card>

  <Card title="Knowledge Bases" icon="book-open">
    Attach one or more knowledge bases for retrieval-augmented responses during live calls.
  </Card>

  <Card title="Tools" icon="zap">
    Let the LLM call tools mid-conversation: knowledge, APIs, endpoint prompts, transfer, hold, and end session.
  </Card>

  <Card title="Deployments" icon="phone">
    Run the same assistant across phone, web, and WhatsApp with channel-specific voice settings.
  </Card>

  <Card title="Webhooks" icon="activity">
    Stream conversation events, transcripts, and metadata to your external systems in real time.
  </Card>

  <Card title="Post-call Analysis" icon="bar-chart">
    Run post-call analysis for sentiment, intent, compliance, CSAT, and custom metrics.
  </Card>
</CardGroup>

***

## How a voice conversation works

Every conversation follows the same pipeline from audio-in to audio-out. Understanding this flow helps you tune latency, accuracy, and behaviour at each stage.

```mermaid theme={null}
flowchart TD
    A(["🎙 Caller speaks"]) --> B["Voice Activity Detection\nSilero VAD · FireRed VAD"]
    B --> C["Noise Cancellation\nRNNoise — removes background audio before transcription"]
    C --> D["Speech-to-Text\nDeepgram · Azure · AssemblyAI · OpenAI Whisper · Google"]
    D --> E["End-of-Speech Detection\nSilence-Based · Pipecat Smart Turn"]
    E --> F["LLM Inference\nOpenAI · Anthropic · Gemini · Mistral · Bedrock · AgentKit"]
    F --> G{Tool call\nrequested?}
    G -->|Yes| H["Tool Execution\nAPI · Knowledge · Endpoint · Hold"]
    H -->|Result injected back| F
    G -->|No| I["Text-to-Speech\nElevenLabs · Azure · Deepgram · OpenAI · Cartesia"]
    I --> J(["🔊 Caller hears response"])
    J --> K{Conversation\nended?}
    K -->|Next turn| A
    K -->|Session closed| L["Post-call Processing"]
    L --> M["Webhooks\nconversation.completed — transcript, metadata, tool calls"]
    L --> N["Analysis Pipelines\nScoring · Sentiment · Compliance · Custom metrics"]
```

<Note>
  The EOS timeout (default 700ms) is the primary latency control between the caller finishing speaking and the assistant beginning to respond. Reduce it for snappy IVR-style interactions; increase it for conversational use cases where callers pause mid-thought.
</Note>

***

## Deployment channels

The same assistant is deployable across every channel. Each deployment is independently configured for voice settings and conversation experience while sharing the assistant's prompt, model, and tools.

<CardGroup>
  <Card title="Phone" icon="phone" href="/voice-deployment-options/phone">
    Inbound and outbound PSTN calls via Twilio, Vonage, Exotel, Asterisk, or SIP.
  </Card>

  <Card title="Web Widget" icon="globe" href="/voice-deployment-options/web-widget">
    Embeddable widget for text and voice on any site with a script tag.
  </Card>

  <Card title="Web App (React SDK)" icon="monitor" href="/voice-deployment-options/web-app">
    Native React SDK integration with direct WebRTC audio streaming.
  </Card>

  <Card title="WhatsApp" icon="message-circle" href="/voice-deployment-options/whatsapp">
    Deploy on WhatsApp Business with multi-turn context across messages.
  </Card>

  <Card title="API / SDK" icon="terminal" href="/api-reference/installation">
    Programmatically create calls, pass variables, stream transcripts, and consume webhooks.
  </Card>

  <Card title="Debugger" icon="activity" href="/assistants/create-assistant">
    Test live conversations in-browser before release, with real-time logs and tool traces.
  </Card>
</CardGroup>

***

## The assistant lifecycle

```mermaid theme={null}
flowchart LR
    A["1. Create\nLLM + prompt\nv1 draft"] --> B["2. Configure\nVoice · Tools\nKnowledge · Deployments"]
    B --> C["3. Test\nDebugger\nlive conversation"]
    C --> D{Ready\nfor prod?}
    D -->|Yes| E["4. Release\nAll deployments\nswitch instantly"]
    D -->|No| B
    E --> F["5. Monitor\nTranscripts · Latency\nWebhooks · Analysis"]
    F --> G["6. Iterate\nNew version\nin draft"]
    G --> C
```

**1. Create** — Define the assistant with an LLM provider and initial system prompt. The first version (`v1`) is created automatically in draft state.

**2. Configure** — Attach knowledge bases, add tools, tune experience/listen/speak settings, and set up deployments. Each deployment channel has its own runtime configuration.

**3. Test** — Use the built-in Debugger deployment to run live conversations before any real traffic hits the assistant. Inspect transcripts, latency breakdowns, and tool invocations.

**4. Release** — Promote a version from draft to live. All active deployments switch to the released version immediately.

**5. Monitor** — Every conversation generates structured logs: full transcript, per-turn latency, tool call results, LLM token usage, and EOS timing. Webhook events and analysis pipeline outputs flow to your downstream systems.

**6. Iterate** — Create a new version with updated prompt or model parameters. Test in the Debugger. Release when confident. Previous versions are preserved and can be re-released for instant rollback.

<Tip>
  Use separate assistants for distinct products or personas rather than a single assistant with complex conditional logic in the prompt. Assistants are cheap to create — isolation keeps prompts focused and version history clean.
</Tip>

***

## In this section

<CardGroup>
  <Card title="Create an Assistant" icon="plus" href="/assistants/create-assistant">
    Step-by-step guide through creation, prompt setup, model configuration, runtime configuration, and tools.
  </Card>

  <Card title="Voice Activity Detection" icon="shield" href="/assistants/voice-activity-detection">
    Configure VAD providers (Silero, FireRed) — speech detection sensitivity, barge-in timing, and noise handling.
  </Card>

  <Card title="End of Speech Detection" icon="clock" href="/assistants/end-of-speech">
    Configure EOS providers (Silence-Based, Pipecat Smart Turn) — turn detection, latency tuning, and parameter guidance.
  </Card>

  <Card title="Version Control" icon="git-branch" href="/assistants/create-new-version">
    Create, compare, and release new versions. Roll back instantly if something goes wrong.
  </Card>

  <Card title="Tools" icon="zap" href="/assistants/introduction-to-tools">
    Add knowledge retrieval, API calls, endpoint invocations, call transfer, hold, and end-of-conversation tools.
  </Card>

  <Card title="Knowledge" icon="book-open" href="/assistants/knowledge/add-knowledge">
    Attach knowledge bases and tune retrieval settings for your use case.
  </Card>

  <Card title="Webhooks" icon="activity" href="/assistants/webhook/overview">
    Configure event-driven delivery of transcripts and call data to external systems.
  </Card>

  <Card title="Logs" icon="list" href="/activity/conversation-logs">
    Browse conversation transcripts, tool call traces, LLM token usage, and latency breakdowns for every session.
  </Card>

  <Card title="Post-call Analysis" icon="bar-chart" href="/assistants/analysis/overview">
    Run LLM-powered analysis pipelines against completed conversations.
  </Card>

  <Card title="AgentKit" icon="cpu" href="/assistants/agentkit">
    Replace Rapida's built-in LLM with your own gRPC backend — LangChain, CrewAI, or custom logic.
  </Card>

  <Card title="Twilio Integration" icon="phone" href="/assistants/twilio-integration">
    Step-by-step guide for connecting a Twilio phone number to your assistant.
  </Card>
</CardGroup>


# Assistant Prompt Templating
Source: https://doc.rapida.ai/assistants/prompt-templating

How to use runtime prompt variables correctly, with variable meaning tables and production-ready examples.

Prompt templating lets you inject runtime context into assistant instructions so responses are personalized, deterministic, and easier to control.

<Info>
  Treat prompt templates like code: define a stable variable contract, review changes, and version updates before release.
</Info>

***

## Why This Matters

| Without templating                  | With templating                           |
| ----------------------------------- | ----------------------------------------- |
| Generic responses                   | Context-aware responses                   |
| Hard-coded business values          | Runtime values from your app/call context |
| Prompt duplication across use cases | One reusable prompt with variables        |

***

## Variable Access Styles

You can access runtime arguments in two equivalent ways:

| Style      | Example                    | When to prefer                            |
| ---------- | -------------------------- | ----------------------------------------- |
| Namespaced | `{{ args.customer_name }}` | Best default, explicit and safer          |
| Root-level | `{{ customer_name }}`      | Short prompts, low risk of key collisions |

<Note>
  Use `args.*` for most custom business fields. It makes prompts easier to maintain as your variable set grows.
</Note>

<Tip>
  If your team has multiple developers editing prompts, enforce a naming convention like `args.customer_*`, `args.order_*`, `args.billing_*`.
</Tip>

***

## General Jinja-Style Guidelines

Rapida prompt rendering uses **Pongo2** (Jinja-style syntax).\
Use this safe subset for predictable behavior:

| Pattern                | Example                                      | Use for                         |
| ---------------------- | -------------------------------------------- | ------------------------------- |
| Variable interpolation | `{{ args.customer_name }}`                   | inject runtime values           |
| Conditionals           | `{% if message.language %}...{% endif %}`    | optional sections/fallback flow |
| Loops                  | `{% for m in messages %}...{% endfor %}`     | render repeated structures      |
| Autoescape control     | `{% autoescape off %}...{% endautoescape %}` | preserve raw output blocks      |

<Info>
  Supported patterns above are validated by parser tests in `pkg/parsers/pongo2_template_parser_test.go`.
</Info>

<Warning>
  Keep template logic lightweight. Put business decision logic in instructions and runtime data, not deeply nested template control flow.
</Warning>

***

## Built-in Variables (What + Why)

### `system.*`

| Variable                  | What it is                        | Why it is useful                                    |
| ------------------------- | --------------------------------- | --------------------------------------------------- |
| `system.current_date`     | UTC date (YYYY-MM-DD)             | Date-sensitive flows (appointments, policy windows) |
| `system.current_time`     | UTC time (HH:MM:SS)               | Time-gated behavior                                 |
| `system.current_datetime` | UTC datetime (RFC3339)            | Logging-style prompts or strict audit wording       |
| `system.day_of_week`      | UTC weekday name                  | Business-hour or weekday-specific logic             |
| `system.date_rfc1123`     | UTC RFC1123 date string           | Interop with strict date formats                    |
| `system.date_unix`        | UTC Unix timestamp (seconds)      | Numeric date comparisons                            |
| `system.date_unix_ms`     | UTC Unix timestamp (milliseconds) | High-precision timing context                       |

### `assistant.*`

| Variable                | What it is            | Why it is useful                        |
| ----------------------- | --------------------- | --------------------------------------- |
| `assistant.name`        | Assistant name        | Consistent self-introduction            |
| `assistant.id`          | Assistant identifier  | Tracing/debug references                |
| `assistant.description` | Assistant description | Reinforce role/context in-system prompt |

### `conversation.*`

| Variable                    | What it is                    | Why it is useful                |
| --------------------------- | ----------------------------- | ------------------------------- |
| `conversation.id`           | Conversation ID               | Support/debug workflows         |
| `conversation.identifier`   | Conversation identifier       | Personalized behavior           |
| `conversation.source`       | Conversation source           | Channel-specific instructions   |
| `conversation.direction`    | Inbound/outbound direction    | Different call-opening behavior |
| `conversation.created_date` | Conversation created datetime | SLA or timing-aware responses   |

### `message.*`

| Variable           | What it is               | Why it is useful                           |
| ------------------ | ------------------------ | ------------------------------------------ |
| `message.language` | Current message language | Multilingual behavior and response control |
| `message.text`     | Current message text     | Ground immediate response                  |

***

## Practical Production Example

```text theme={null}
You are {{ assistant.name }}, a billing support assistant for {{ args.company_name }}.

Context:
- Customer: {{ args.customer_name }}
- Plan: {{ args.plan_name }}
- Outstanding balance: {{ args.balance_amount }} {{ args.currency }}
- Channel: {{ conversation.source }}
- Current date: {{ system.current_date }}

Behavior:
1. If balance_amount is empty, ask for account verification before billing help.
2. Keep replies under 2 short sentences for voice clarity.
3. If message.language is set, respond in that language.
4. Never invent invoice IDs. If missing, say data is unavailable and ask to verify.
```

***

## Runtime Argument Example (from your app/backend)

```json theme={null}
{
  "company_name": "Acme Telecom",
  "customer_name": "Priya",
  "plan_name": "Business Pro",
  "balance_amount": "129.00",
  "currency": "USD"
}
```

This enables both:

* `{{ args.customer_name }}`
* `{{ customer_name }}`

<Info>
  Use one canonical style in production prompts (recommended: `args.*`) even though both styles resolve.
</Info>

***

## UX Guidelines for Better Prompts

| Guideline                                                    | Why                                |
| ------------------------------------------------------------ | ---------------------------------- |
| Prefer explicit variable names (`customer_name`, not `name`) | Reduces ambiguity in long prompts  |
| Group business fields under `args.*`                         | Easier schema evolution            |
| Add fallback instruction for missing variables               | Prevents hallucinated placeholders |
| Keep voice responses short in instructions                   | Better TTS experience              |
| Keep key names stable across versions                        | Avoid silent prompt regressions    |

***

## Common Mistakes

| Mistake                                                     | Better approach                               |
| ----------------------------------------------------------- | --------------------------------------------- |
| Using many root-level short keys                            | Use `args.*` namespaced fields                |
| Assuming every field is always present                      | Add fallback rules in prompt                  |
| Mixing formatting instructions with business logic randomly | Separate into `Context` and `Behavior` blocks |
| Rewriting prompts per customer                              | Reuse one template with runtime args          |

<Warning>
  Do not assume every runtime variable is always present. Add explicit fallback behavior in the prompt for missing or empty values.
</Warning>

<Tip>
  For voice assistants, add a hard instruction such as: “Keep responses under 2 short sentences unless the user asks for details.”
</Tip>

***

## Related Pages

* [Create assistant](/assistants/create-assistant)
* [Assistant Telemetry](/assistants/telemetry)
* [Assistant API — Prompt Templating](/opensource/services/assistant-api/prompt-templating)


# Speech-to-Text
Source: https://doc.rapida.ai/assistants/speech-to-text

Configure STT providers, credentials, models, language, and transcription tuning for Rapida voice assistants.

Speech-to-Text (STT) converts user speech into text for the assistant. STT quality affects everything downstream: the LLM only sees what the transcription provider returns.

```mermaid theme={null}
flowchart LR
    A["User audio"] --> B["Noise cancellation"]
    B --> C["Voice Activity Detection"]
    C --> D["Speech-to-Text"]
    D --> E["End of Speech"]
    E --> F["LLM + tools"]
```

<Info>
  STT is configured in the **Voice Input** step of a Phone Call, Web Widget, or Web App / SDK deployment.
</Info>

## Setup flow

<Steps>
  <Step title="Create the provider credential">
    Add the STT provider credential in **Credentials**. The deployment wizard can only select credentials that already exist.
  </Step>

  <Step title="Open the deployment voice input step">
    Go to **Configure Assistant** -> **Deployments**, create or edit a voice-capable deployment, then open **Voice Input**.
  </Step>

  <Step title="Choose the STT provider">
    Select the provider that will transcribe user audio.
  </Step>

  <Step title="Select the model">
    Choose the provider-specific model. For phone calls, prefer real-time or telephony-friendly models. For browser audio, use the provider's recommended real-time model.
  </Step>

  <Step title="Set language when required">
    Select the primary user language when the provider requires it. Use multilingual or automatic detection only when the provider supports it and your use case needs it.
  </Step>

  <Step title="Tune advanced voice input">
    Configure noise cancellation, VAD, and EOS from **Show advanced settings**. These settings control what audio reaches STT and when a user turn is complete.
  </Step>
</Steps>

## Supported providers

| Provider                 | Typical use                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Deepgram                 | Low-latency streaming transcription and telephony use cases.      |
| AssemblyAI               | Real-time transcription with strong conversation-oriented models. |
| Azure Cognitive Services | Enterprise Microsoft environments and multilingual deployments.   |
| Google Speech Service    | Google Cloud speech recognition workflows.                        |
| OpenAI                   | OpenAI transcription models for voice applications.               |
| AWS Transcribe           | AWS-native speech recognition.                                    |
| Cartesia                 | Voice AI workflows that also use Cartesia TTS.                    |
| Sarvam AI                | Indian language voice applications.                               |
| Groq                     | Low-latency Whisper-compatible transcription.                     |
| Speechmatics             | Broad language coverage and accent robustness.                    |
| NVIDIA                   | NVIDIA-hosted speech models.                                      |
| Custom STT               | Your own WebSocket-compatible STT backend.                        |

## Configuration fields

The exact fields vary by provider, but STT configuration usually includes:

| Field      | What it controls                                                             |
| ---------- | ---------------------------------------------------------------------------- |
| Credential | Which stored provider credential Rapida uses.                                |
| Model      | The transcription model. This is usually the main accuracy/latency tradeoff. |
| Language   | The expected user language or provider language code.                        |

Some providers expose only a model because language is inferred, encoded in the model, or configured provider-side.

## Choosing a provider

| Need               | Recommended direction                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Lowest latency     | Use a provider with streaming transcription and a real-time model.                                                                    |
| Phone calls        | Choose a model that handles 8 kHz telephony audio well.                                                                               |
| Browser microphone | Use a real-time model that performs well on cleaner wideband audio.                                                                   |
| Noisy environments | Pair the provider with [Noise Cancellation](/assistants/noise-cancellation) and stricter [VAD](/assistants/voice-activity-detection). |
| Multilingual users | Use explicit language selection or a provider with reliable language detection.                                                       |
| Private provider   | Use [Custom STT](/integrations/stt/custom).                                                                                           |

<Warning>
  Do not judge STT accuracy from one setting alone. Wrong VAD, disabled noise cancellation, or aggressive EOS can produce clipped or incomplete audio that looks like an STT issue.
</Warning>

## Channel guidance

### Phone calls

Phone calls often use narrowband or compressed audio. Prefer STT models that are tested for telephony and real-time streaming. Keep RNNoise enabled for most phone deployments.

Start with:

| Area               | Starting point                                                   |
| ------------------ | ---------------------------------------------------------------- |
| Model              | Real-time or telephony-friendly model.                           |
| Noise cancellation | RNNoise enabled.                                                 |
| VAD                | Silero VAD with balanced confidence and 0.2s start/stop windows. |
| EOS                | Pipecat Smart Turn or Silence-Based at 700-1000 ms.              |

### Web widget and web app

Browser microphone audio is often cleaner than phone audio, but user environments vary widely. Use a real-time model and test with laptop microphones, headsets, and mobile browsers.

Start with:

| Area               | Starting point                               |
| ------------------ | -------------------------------------------- |
| Model              | Real-time model for browser audio.           |
| Noise cancellation | Enabled for uncontrolled environments.       |
| VAD                | Silero VAD.                                  |
| EOS                | Pipecat Smart Turn for natural conversation. |

## Troubleshooting

| Symptom                                        | Likely cause                                | What to adjust                                                   |
| ---------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| Transcripts miss quiet speech                  | VAD confidence too high or wrong STT model  | Lower VAD confidence and test another STT model.                 |
| Transcripts include background noise           | Noise cancellation off or VAD too sensitive | Enable RNNoise and raise VAD confidence.                         |
| User words are cut off at the beginning        | VAD speech confirmation too strict          | Reduce VAD start seconds or lower VAD confidence.                |
| Assistant responds to incomplete transcript    | EOS too aggressive                          | Tune [End of Speech Detection](/assistants/end-of-speech).       |
| Multilingual users are transcribed incorrectly | Language mismatch                           | Set the correct language or use a multilingual-capable provider. |

## Related

<CardGroup>
  <Card title="Listen" icon="mic" href="/assistants/configuration/listen">
    See how STT fits into speech input configuration.
  </Card>

  <Card title="Noise Cancellation" icon="audio-waveform" href="/assistants/noise-cancellation">
    Clean audio before it reaches STT.
  </Card>

  <Card title="Custom STT" icon="settings" href="/integrations/stt/custom">
    Connect a custom WebSocket transcription provider with DSL rules.
  </Card>

  <Card title="Voice Activity Detection" icon="activity" href="/assistants/voice-activity-detection">
    Tune when user speech starts and stops.
  </Card>

  <Card title="End of Speech Detection" icon="clock" href="/assistants/end-of-speech">
    Decide when the transcript is ready for the assistant to answer.
  </Card>
</CardGroup>


# Assistant Telemetry
Source: https://doc.rapida.ai/assistants/telemetry

Configure telemetry providers, understand required fields, and use telemetry records for debugging and optimization.

Assistant telemetry exports runtime events and metrics so you can debug behavior, monitor latency, and validate production quality.

<Info>
  Configure telemetry per assistant so you can isolate behavior by product, environment, or use case.
</Info>

***

## Why Telemetry Is Useful

| Use case               | What telemetry gives you                           |
| ---------------------- | -------------------------------------------------- |
| Debugging failed calls | Event timeline + error events                      |
| Performance tuning     | STT/LLM/TTS timing and metric scopes               |
| Release validation     | Compare behavior before/after prompt/model changes |
| Incident triage        | Filter by conversation ID / message ID quickly     |

***

## Where to Configure

| Screen              | Action                       |
| ------------------- | ---------------------------- |
| Assistants          | Open target assistant        |
| Configure Assistant | Open **Telemetry** tab       |
| Telemetry page      | Add / edit / delete provider |

Routes used by UI:

| Route                                                                 | Purpose         |
| --------------------------------------------------------------------- | --------------- |
| `/deployment/assistant/:assistantId/configure-telemetry`              | List providers  |
| `/deployment/assistant/:assistantId/configure-telemetry/create`       | Create provider |
| `/deployment/assistant/:assistantId/configure-telemetry/:telemetryId` | Update provider |

<Note>
  Saving a provider stores configuration for the assistant. Runtime export depends on the provider being enabled.
</Note>

***

## Supported Providers (UI)

| Provider      | Code            | Typical use                     |
| ------------- | --------------- | ------------------------------- |
| OTLP          | `otlp_http`     | Generic OpenTelemetry pipelines |
| Datadog       | `datadog`       | Datadog tracing/APM             |
| AWS X-Ray     | `xray`          | AWS-native trace pipeline       |
| Google Trace  | `google_trace`  | GCP trace pipeline              |
| Azure Monitor | `azure_monitor` | Azure monitoring stack          |

***

## Required and Optional Fields

| Field                               | Required           | Why it exists                              |
| ----------------------------------- | ------------------ | ------------------------------------------ |
| Credential (`rapida.credential_id`) | Yes                | Supplies auth/config values from vault     |
| Endpoint                            | Yes                | Destination address for exporter           |
| Protocol                            | Provider-dependent | Transport behavior                         |
| Insecure                            | Optional           | TLS relaxation for controlled environments |
| Region (`xray`)                     | Optional           | AWS regional routing                       |

Provider-specific UI fields:

| Provider        | Fields shown in UI                 |
| --------------- | ---------------------------------- |
| `otlp_http`     | `endpoint`, `protocol`, `insecure` |
| `datadog`       | `endpoint`, `insecure`             |
| `xray`          | `endpoint`, `region`, `insecure`   |
| `google_trace`  | `endpoint`, `insecure`             |
| `azure_monitor` | `endpoint`, `insecure`             |

<Warning>
  If credential or endpoint is invalid, telemetry export will fail at runtime even if the provider configuration is saved.
</Warning>

***

## Enabled vs Disabled

| Status   | Behavior                                        |
| -------- | ----------------------------------------------- |
| Enabled  | Provider is loaded and used in runtime export   |
| Disabled | Configuration is saved but exporter is not used |

<Tip>
  Use disabled providers as staged configs when testing new exporters, then enable after validation.
</Tip>

***

## Reading Conversation Telemetry

The conversation telemetry modal combines event and metric records.

Available filters:

| Filter key       | What to use it for            |
| ---------------- | ----------------------------- |
| `conversationId` | Analyze one full conversation |
| `messageId`      | Analyze one specific turn     |
| `name`           | Find specific event types     |
| `scope`          | Narrow to metric scope        |

***

## Example Debug Workflow

| Step | Action                                       | Outcome                   |
| ---- | -------------------------------------------- | ------------------------- |
| 1    | Filter by `conversationId`                   | isolate one call          |
| 2    | Check event sequence (`stt` → `llm` → `tts`) | verify pipeline order     |
| 3    | Filter by `messageId` for slow turn          | isolate latency spike     |
| 4    | Inspect metric scope entries                 | identify bottleneck stage |
| 5    | Update prompt/voice settings and re-test     | validate improvement      |

<Tip>
  When comparing releases, run the same scenario twice and compare telemetry for the same stage (`stt`, `llm`, `tts`) to confirm regression or improvement.
</Tip>

***

## Related Pages

* [Prompt templating](/assistants/prompt-templating)
* [Conversation logs](/activity/conversation-logs)
* [Assistant API — Telemetry](/opensource/services/assistant-api/telemetry)


# Text-to-Speech
Source: https://doc.rapida.ai/assistants/text-to-speech

Configure TTS providers, voices, languages, pronunciation, ambient audio, and speech delivery for Rapida voice assistants.

Text-to-Speech (TTS) converts the assistant's text response into spoken audio. It controls how the assistant sounds, how quickly users hear the first audio, and how clearly domain-specific terms are pronounced.

```mermaid theme={null}
flowchart LR
    A["LLM + tools"] --> B["Assistant text"]
    B --> C["Text-to-Speech"]
    C --> D["User hears response"]
```

<Info>
  TTS is configured in the **Voice Output** step of a Phone Call, Web Widget, or Web App / SDK deployment.
</Info>

## Setup flow

<Steps>
  <Step title="Create the provider credential">
    Add the TTS provider credential in **Credentials** before configuring the deployment.
  </Step>

  <Step title="Open the deployment voice output step">
    Go to **Configure Assistant** -> **Deployments**, create or edit a voice-capable deployment, then open **Voice Output**.
  </Step>

  <Step title="Choose the TTS provider">
    Select the provider that will synthesize assistant responses.
  </Step>

  <Step title="Choose the model">
    Select the provider-specific model. Some providers optimize for lowest latency, while others optimize for voice quality.
  </Step>

  <Step title="Choose the voice">
    Select the voice ID. For providers that support custom voices, use the custom voice ID when the field allows custom values.
  </Step>

  <Step title="Set the language">
    Match the TTS language to the assistant's expected response language and selected voice.
  </Step>
</Steps>

## Supported providers

| Provider                 | Typical use                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| ElevenLabs               | Natural voices, custom voices, and brand voice workflows.          |
| Deepgram                 | Low-latency streaming voice output.                                |
| Azure Cognitive Services | Enterprise Microsoft environments and broad voice catalog support. |
| Google Speech Service    | Google Cloud text-to-speech workflows.                             |
| OpenAI                   | OpenAI TTS models and voices.                                      |
| AWS Polly                | AWS-native neural and standard voices.                             |
| Cartesia                 | Low-latency voice AI and expressive voice controls.                |
| Rime                     | Real-time voice synthesis with provider voices.                    |
| Sarvam AI                | Indian language voice output.                                      |
| Resemble AI              | Custom and cloned voice workflows.                                 |
| Neuphonic                | Low-latency conversational TTS.                                    |
| MiniMax                  | Voice models from MiniMax.                                         |
| Groq                     | Low-latency TTS through Groq-supported models.                     |
| Speechmatics             | Speechmatics voice output.                                         |
| NVIDIA                   | NVIDIA-hosted voice models.                                        |
| Custom TTS               | Your own WebSocket-compatible TTS backend.                         |

## Configuration fields

The exact fields vary by provider, but TTS configuration usually includes:

| Field            | What it controls                               |
| ---------------- | ---------------------------------------------- |
| Credential       | Which stored provider credential Rapida uses.  |
| Model            | The speech synthesis model.                    |
| Voice            | The voice ID or custom voice identifier.       |
| Language         | The output language or locale.                 |
| Speed or emotion | Provider-specific controls for speaking style. |

## Advanced speech settings

Open **Show advanced settings** in Voice Output to tune delivery.

| Setting                    | What it controls                                                                                                 | Default  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------- |
| Ambient                    | Optional background ambience mixed into output audio.                                                            | `none`   |
| Ambient Volume             | Volume of the selected ambience.                                                                                 | `18`     |
| Pronunciation Dictionaries | Built-in pronunciation rules for currencies, dates, times, numbers, addresses, URLs, abbreviations, and symbols. | none     |
| Conjunction Boundaries     | Words where Rapida can add natural pause boundaries.                                                             | none     |
| Pause Duration             | Pause length at configured conjunction boundaries.                                                               | `240 ms` |

### Pronunciation dictionaries

Use pronunciation dictionaries when the assistant must say structured or domain-specific text clearly.

| Dictionary type                                                  | Helps with                               |
| ---------------------------------------------------------------- | ---------------------------------------- |
| `currency`                                                       | Prices, amounts, and currency symbols.   |
| `date` and `time`                                                | Dates, appointment times, and schedules. |
| `numeral`                                                        | Account numbers, quantities, and IDs.    |
| `address`                                                        | Street addresses and postal details.     |
| `url`                                                            | Websites and links.                      |
| `tech-abbreviation`, `role-abbreviation`, `general-abbreviation` | Acronyms and abbreviations.              |
| `symbol`                                                         | Symbols that should be spoken naturally. |

<Tip>
  Add pronunciation dictionaries before user testing. Mispronounced product names, acronyms, prices, dates, and addresses are easy for users to notice.
</Tip>

### Conjunction boundaries

Conjunction boundaries let Rapida add natural pauses around selected words such as `and`, `but`, `or`, `because`, and `while`. This can make long responses easier to listen to.

Use them when:

* The assistant often speaks multi-clause sentences.
* Users need time to understand instructions.
* TTS output feels rushed even when the voice is good.

Avoid overusing them when:

* The assistant already speaks in very short sentences.
* The added pauses make responses feel slow.

## Choosing a provider

| Need                    | Recommended direction                                                               |
| ----------------------- | ----------------------------------------------------------------------------------- |
| Lowest response latency | Use a streaming TTS provider and keep assistant responses short.                    |
| Natural voice quality   | Use a neural or conversational voice model.                                         |
| Brand voice             | Use a provider that supports cloned or custom voice IDs.                            |
| Multilingual speech     | Choose a voice that supports the required language, not only a model that lists it. |
| Phone calls             | Test the voice over phone audio, not only in browser previews.                      |
| Private provider        | Use [Custom TTS](/integrations/tts/custom).                                         |

## Prompt guidance for better TTS

TTS quality depends on the text the LLM produces. Tune the assistant prompt for spoken responses:

* Keep responses under one or two short sentences.
* Avoid markdown, bullet lists, long tables, and symbols.
* Ask one question at a time.
* Confirm critical values slowly, especially emails, phone numbers, dates, and addresses.
* Write instructions in natural spoken language.

## Troubleshooting

| Symptom                           | Likely cause                           | What to adjust                                                                          |
| --------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
| First audio starts slowly         | TTS model latency or long LLM response | Use lower-latency TTS and shorten assistant responses.                                  |
| Voice mispronounces product names | Missing pronunciation handling         | Enable pronunciation dictionaries or use a provider custom voice/pronunciation feature. |
| Voice sounds rushed               | Long clauses or no pauses              | Add conjunction boundaries and lower prompt response length.                            |
| Voice sounds unnatural on phone   | Voice tested only on browser audio     | Test through the target phone deployment and try a clearer voice.                       |
| Wrong language or accent          | Voice and language mismatch            | Select a language-matched voice and provider model.                                     |

## Related

<CardGroup>
  <Card title="Speak" icon="volume-2" href="/assistants/configuration/speak">
    See where TTS fits into spoken output configuration.
  </Card>

  <Card title="Speech-to-Text" icon="mic" href="/assistants/speech-to-text">
    Configure user speech transcription.
  </Card>

  <Card title="Custom TTS" icon="settings" href="/integrations/tts/custom">
    Connect a custom WebSocket speech synthesis provider with DSL rules.
  </Card>

  <Card title="Phone Call Deployment" icon="phone" href="/voice-deployment-options/phone">
    Configure required voice output for phone calls.
  </Card>

  <Card title="Web App / SDK Deployment" icon="monitor" href="/voice-deployment-options/web-app">
    Configure optional voice output for custom apps.
  </Card>
</CardGroup>


# API Call Tool
Source: https://doc.rapida.ai/assistants/tools/add-api-tool

Configure and use the API Call Tool to make external API requests

The API Call Tool allows your assistant to make external API requests when responding to user queries. This guide will walk you through the process of adding and configuring this tool for your assistant.

## Prerequisites

Before adding the API Call Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)

## Adding the API Call Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click on **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    Configure the API Call Tool with the following settings:

    1. **Name**: A unique identifier for your tool (e.g., "fetch\_user\_details")
       * Use descriptive names that indicate the tool's purpose
       * Follow a consistent naming convention (e.g., snake\_case)

    2. **Description**: Details on when and how to use the function
       * Example: "Fetch user name and user role"
       * Provide clear guidance on the tool's purpose and use cases
       * This helps the model determine when to invoke the tool

    3. **Fields**: Define parameters in JSON format following the OpenAI Function Tool Call schema:

       ```json theme={null}
       {
         "additionalProperties": false,
         "properties": {
           "user_name": {
             "description": "name of user",
             "type": "string"
           },
            "user_role": {
             "description": "role of user",
             "type": "string"
           }
         },
          "required": ["user_name", "user_role"]
       }
       ```

       This schema follows the OpenAI Function Tool Call format where `additionalProperties: false` ensures only defined properties are allowed, `properties` defines the parameters the tool accepts with descriptions and data types for each, and `required` specifies which parameters must be included.

    4. **Expected Action**: Select "API Request" from the dropdown.

    5. **Method**: Choose the appropriate HTTP method (GET, POST, PUT, PATCH, etc.)

    6. **Server URL**: Enter the URL of the external API server

    7. **Headers**: Add any necessary HTTP headers as key-value pairs

    8. **Parameters**: Add any query parameters or body parameters as key-value pairs
  </Step>

  <Step title="Configure Endpoint Settings">
    Set up the API endpoint details:

    * **Method**: Select the appropriate HTTP method (GET, POST, PUT, PATCH, DELETE)
    * **Server URL**: Enter the URL of the external API server
  </Step>

  <Step title="Add Headers">
    Configure any HTTP headers needed for your API request:

    * Click **Add header** to include authentication headers or other required metadata
    * Common examples include API keys, Content-Type headers, or Authorization tokens
  </Step>

  <Step title="Configure Parameters">
    Add parameters to be sent with your API request:

    1. Click **Add parameters** to include data in your request
    2. Select the parameter type from the dropdown menu:

    <AccordionGroup>
      <Accordion title="Assistant">
        Include assistant-related information in the request:

        * Name
        * Prompt
      </Accordion>

      <Accordion title="Conversation">
        Include conversation data in the request:

        * Conversation history
      </Accordion>

      <Accordion title="Argument">
        * Include any arguments passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
      </Accordion>

      <Accordion title="Metadata">
        * Custom metadata that you want to send
      </Accordion>

      <Accordion title="Option">
        * Include configuration options passed to the assistant. Key is the name passed, value is the new key that will be passed to the api call.
      </Accordion>
    </AccordionGroup>

    You can add multiple parameters to construct a complete API request.
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click on the **Configure Tool** button to save your changes.
  </Step>
</Steps>

## Using the API Call Tool

Once configured, your assistant can use the API Call Tool when appropriate. The process typically follows these steps:

1. The assistant determines a need for external data or functionality.
2. It calls the API Call Tool with the necessary parameters.
3. The tool makes an API request to the specified endpoint.
4. The assistant incorporates the response from the external API into its own response.

## Managing the API Call Tool

You can modify or remove the API Call Tool at any time:

1. Go to your assistant's "Manage" -> "Configure Tool" tab.
2. Find the API Call Tool in the list.
3. Click on it to modify its configuration or remove it.

## Best Practices

* Ensure the external API endpoints are reliable and secure.
* Monitor API usage and costs associated with external calls.
* Use the tool judiciously to balance between built-in capabilities and external data fetching.
* Regularly review and update the tool's configuration to optimize performance.

By effectively configuring and utilizing the API Call Tool, your assistant can leverage external APIs for enhanced capabilities and access to real-time data or services.


# End of Conversation Tool
Source: https://doc.rapida.ai/assistants/tools/add-end-of-conversation-tool

Configure and use the End of Conversation Tool to signal the end of a conversation

The End of Conversation Tool allows your assistant to explicitly signal when a conversation should end. This guide will walk you through the process of adding and configuring this tool for your assistant.

## Prerequisites

Before adding the End of Conversation Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)

## Adding the End of Conversation Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click on **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    When configuring an End of Conversation tool, you'll need to provide several key elements:

    1. **Name**: A unique identifier for your tool
       * Example: "end\_conversation"
       * Use descriptive names that indicate the tool's purpose

    2. **Description**: Details on when and how to use the function
       * Example: "Ends the conversation after a task is complete or the user says goodbye."
       * This helps the model determine when to invoke the tool

    3. **Fields**: Define parameters in JSON format following the OpenAI Function Tool Call schema:

       ```json theme={null}
       {
         "type": "object",
         "properties": {}
       }
       ```

       This simple schema indicates that the tool doesn't require any specific parameters.

    4. **Expected Action**: From the list select "End Of Conversation".
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click on the **Configure Tool** button to apply your changes.
  </Step>
</Steps>

<img alt="Put on hold" />

## Using the End of Conversation Tool

Once configured, your assistant can use the End of Conversation Tool when appropriate. The process typically follows these steps:

1. The assistant determines that the conversation has reached a natural conclusion.
2. It calls the End of Conversation Tool.
3. The conversation is marked as ended, and the assistant stops generating further responses.

## Managing the End of Conversation Tool

You can modify or remove the End of Conversation Tool at any time:

1. Go to your assistant's configuration page.
2. Select "Tools and MCP" from the left sidebar menu.
3. Find the End of Conversation Tool in the list.
4. Click on **Edit Tool** to modify its configuration or **Delete Tool** to delete it.

## Best Practices

* Use the tool when the conversation has reached a logical conclusion.
* Ensure the assistant provides a clear and polite closing message before ending the conversation.
* Configure the tool to align with your specific use case and conversation flow.
* Regularly review conversations to ensure the tool is being used appropriately.

By effectively configuring and utilizing the End of Conversation Tool, your assistant can gracefully conclude interactions, improving user experience and conversation management.


# Endpoint (LLM Call) Tool
Source: https://doc.rapida.ai/assistants/tools/add-endpoint-tool

Configure and use the Endpoint (LLM Call) Tool to make API calls to language models

The Endpoint (LLM Call) Tool allows your assistant to make API calls to language models when responding to user queries. This guide will walk you through the process of adding and configuring this tool for your assistant.

## Prerequisites

Before adding the Endpoint (LLM Call) Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)
* [Created an endpoint](/endpoint/create-endpoint)

## Adding the Endpoint (LLM Call) Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click on **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    When configuring an Endpoint (LLM Call) tool, you'll need to provide several key elements:

    1. **Name**: A unique identifier for your tool (e.g., "fetch\_user\_details")
       * Use descriptive names that indicate the tool's purpose
       * Follow a consistent naming convention (e.g., snake\_case)

    2. **Description**: Details on when and how to use the function
       * Example: "Fetch user name and user role"
       * Provide clear guidance on the tool's purpose and use cases
       * This helps the model determine when to invoke the tool

    3. **Fields**: Define parameters in JSON format following the OpenAI Function Tool Call schema:

       ```json theme={null}
       {
         "additionalProperties": false,
         "properties": {
           "user_name": {
             "description": "name of user",
             "type": "string"
           },
            "user_role": {
             "description": "role of user",
             "type": "string"
           }
         },
          "required": ["user_name", "user_role"]
       }
       ```

       This schema follows the OpenAI Function Tool Call format where `additionalProperties: false` ensures only defined properties are allowed, `properties` defines the parameters the tool accepts with descriptions and data types, and `required` specifies which parameters must be included.

    4. **Expected Action**: From the list select "Endpoint (LLM Call)".

    5. **Endpoint Selection**: Choose an existing endpoint from the dropdown, or create a new one.
       * Select from the dropdown list of available endpoints
       * Or create a [new endpoint](/endpoint/create-endpoint) directly
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click on the **Configure Tool** button to apply your changes.
  </Step>
</Steps>

## Using the Endpoint (LLM Call) Tool

Once configured, your assistant will automatically use the Endpoint Tool when appropriate. The process typically follows these steps:

1. The assistant analyzes the user's query or conversation context.
2. If a specialized task is needed, it calls the Endpoint Tool with the necessary parameters.
3. The tool makes an API call to the specified endpoint language model.
4. The assistant incorporates the response from the endpoint language model into its reply.

## Managing the Endpoint (LLM Call) Tool

You can modify or remove the Endpoint Tool at any time:

1. Go to your assistant's configuration page.
2. Select "Tools and MCP" from the left sidebar menu.
3. Find the Endpoint Tool in the list.
4. Click on **Edit Tool** to modify its configuration or **Delete Tool** to delete it.

## Best Practices

* Use the Endpoint Tool for specialized tasks that benefit from additional LLM capabilities.
* Consider performance implications when making additional API calls.
* Carefully craft prompts to get the most relevant results from additional models.
* Test different model configurations to find the optimal settings for your use case.

By effectively configuring and utilizing the Endpoint (LLM Call) Tool, your assistant can leverage specialized language models to enhance its capabilities and provide more sophisticated responses to complex user queries.


# Knowledge Retrieval Tool
Source: https://doc.rapida.ai/assistants/tools/add-knowledge-tool

Configure and use the Knowledge Retrieval Tool to access information from your knowledge base

The Knowledge Retrieval Tool allows your assistant to fetch relevant information from your organization's knowledge base when responding to user queries. This guide will walk you through the process of adding and configuring this tool for your assistant.

## Prerequisites

Before adding the Knowledge Retrieval Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)
* [Configured a knowledge base](/knowledge/create-knowledge)

## Adding the Knowledge Retrieval Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click on **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    When configuring a Knowledge Retrieval tool, you'll need to provide several key elements:

    1. **Name**: A unique identifier for your tool (e.g., "knowledge\_retrieval\_challenges")
       * Use descriptive names that indicate the tool's purpose
       * Follow a consistent naming convention (e.g., snake\_case)

    2. **Description**: Details on when and how to use the function
       * Example: "retrieve challenges for user role and user industry"
       * Provide clear guidance on the tool's purpose and use cases
       * This helps the model determine when to invoke the tool

    3. **Fields**: Define parameters in JSON format following the OpenAI Function Tool Call schema:

       ```json theme={null}
       {
         "additionalProperties": false,
         "properties": {
           "query": {
             "description": "user role and user industry",
             "type": "string"
           }
         }
       }
       ```

       This schema follows the OpenAI Function Tool Call format where `additionalProperties: false` ensures only defined properties are allowed, `properties` defines the parameters the tool accepts with descriptions and data types for each (like `query`), and the schema validates inputs when the tool is called.

    4. **Expected Action**: From the list select "Knowledge Retrieval".

    5. **Knowledge**: Choose an existing knowledge from the dropdown, or create new.
       * Select from the dropdown list of available sources
       * Or create a [new knowledge](/assistants/knowledge/add-knowledge) source directly

    6. **Retrieval Setting**: Select a search method:
       * **Hybrid Search**: Combines full-text and vector searches for optimal results
       * **Semantic Search**: Uses vector embeddings to find semantically similar content
       * **Full Text Search**: Indexes all terms for keyword-based retrieval

    7. Configure **Top K** results (default: 5) to limit the number of results returned

    8. Set a **Score Threshold** (default: 0.5) for relevance filtering

    After configuring all parameters, click "Save tool" to add it to your assistant.
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click on the **Configure Tool** button to apply your changes.
  </Step>
</Steps>

## Using the Knowledge Retrieval Tool

Once configured, your assistant will automatically use the Knowledge Retrieval Tool when appropriate. The process typically follows these steps:

1. The assistant analyzes the user's query or conversation context.
2. If relevant, it calls the Knowledge Retrieval Tool with the necessary parameters.
3. The tool fetches information from the knowledge base.
4. The assistant incorporates the retrieved information into its response.

## Managing the Knowledge Retrieval Tool

You can modify or remove the Knowledge Retrieval Tool at any time:

1. Go to your assistant's configuration page.
2. Select "Tools and MCP" from the left sidebar menu.
3. Find the Knowledge Retrieval Tool in the list.
4. Click on **Edit Tool** to modify its configuration or **Delete Tool** to delete it.

## Best Practices

* Regularly update your knowledge base to ensure the assistant provides the most current information.
* Monitor your assistant's performance and adjust the tool's configuration as needed.
* Use clear and specific queries to get the most relevant results from the knowledge base.

By effectively configuring and utilizing the Knowledge Retrieval Tool, your assistant can provide more accurate, up-to-date, and relevant information to users based on your organization's specific knowledge resources.


# Put On Hold Tool
Source: https://doc.rapida.ai/assistants/tools/add-put-on-hold-tool

Configure and use the Put On Hold Tool to pause phone calls for a specified duration

The Put On Hold Tool allows your assistant to temporarily pause or put a phone call on hold for a specified number of minutes. This guide will walk you through the process of adding and configuring this tool for your assistant.

## Prerequisites

Before adding the Put On Hold Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)

## Adding the Put On Hold Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click on **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    When configuring a Put On Hold tool, you'll need to provide several key elements:

    1. **Name**: A unique identifier for your tool
       * Example: "put\_on\_hold"
       * Use descriptive names that indicate the tool's purpose

    2. **Description**: Details on when and how to use the function
       * Example: "Call this tool to when user asks to hold."
       * This helps the model determine when to invoke the tool

    3. **Fields**: Define parameters in JSON format following the OpenAI Function Tool Call schema:

       ```json theme={null}
       {
         "type": "object",
         "properties": {}
       }
       ```

       This schema follows the OpenAI Function Tool Call format where `properties` defines the parameters the tool accepts.

    4. **Expected Action**: From the list select "Put On Hold".
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click on the **Configure Tool** button to save your changes.
  </Step>
</Steps>

<img alt="Put on hold" />

## Using the Put On Hold Tool

Once configured, your assistant can use the Put On Hold Tool when appropriate. The process typically follows these steps:

1. The assistant determines a need to pause the conversation or put the call on hold.
2. It calls the Put On Hold Tool with the specified duration.
3. The tool pauses the conversation for the specified number of minutes.
4. After the hold time expires, the assistant resumes the conversation.

## Managing the Put On Hold Tool

You can modify or remove the Put On Hold Tool at any time:

1. Go to your assistant's configuration page.
2. Select "Tools and MCP" from the left sidebar menu.
3. Find the Put On Hold Tool in the list.
4. Click on **Edit Tool** to modify its configuration or **Delete Tool** to delete it.

## Best Practices

* Use the Put On Hold Tool judiciously to avoid prolonged interruptions in the conversation.
* Ensure that the assistant provides a clear explanation to the user before putting the call on hold.
* Consider implementing a callback mechanism if the hold time needs to be extended.
* Regularly review the usage of this tool to optimize the user experience.

By effectively configuring and utilizing the Put On Hold Tool, your assistant can manage conversations more efficiently, allowing for necessary pauses or hold times during phone calls.


# Transfer Call Tool
Source: https://doc.rapida.ai/assistants/tools/add-transfer-call-tool

Configure and use the Transfer Call Tool to hand an active phone call to another phone number or SIP target.

The Transfer Call Tool lets your assistant hand an active phone call to another destination, such as a human agent, queue, department number, or SIP endpoint. Use it when the conversation should leave the AI flow and continue with another party.

## Prerequisites

Before adding the Transfer Call Tool, ensure that you have:

* [Created an assistant](/assistants/create-assistant)
* Configured a phone deployment for a provider that supports live transfer
* A transfer destination, such as an E.164 phone number or SIP URI

## Adding the Transfer Call Tool

<Steps>
  <Step title="Navigate to Your Assistant">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Tools and MCP" from the left sidebar menu.
    5. Click **Add Tools**.
  </Step>

  <Step title="Configure the Tool">
    Configure the Transfer Call Tool with the following settings:

    1. **Name**: A unique identifier for your tool.
       * Example: `transfer_call`
       * Use only letters, numbers, and underscores.

    2. **Description**: Details on when the assistant should transfer the caller.
       * Example: "Transfer the caller to a human support agent when they ask for a person, request escalation, or need help outside the assistant's scope."
       * Mention any confirmation the assistant should collect before transferring.

    3. **Fields**: Define the arguments the model can provide when it calls the tool:

       ```json theme={null}
       {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "transfer_to": {
             "type": "string",
             "description": "Phone number or SIP URI to transfer the call to. Omit this when the tool should always use the configured default destination."
           },
           "transfer_message": {
             "type": "string",
             "description": "Short message the assistant should say before transferring the call."
           },
           "transfer_delay": {
             "type": "number",
             "description": "Delay in milliseconds before dispatching the transfer after the transfer message is played."
           },
           "post_transfer_action": {
             "type": "string",
             "enum": ["end_call", "resume_ai"],
             "description": "What to do after the transfer leg ends. Use end_call for one-way transfers. Use resume_ai only on channels that support bridge transfer."
           }
         },
         "required": []
       }
       ```

       If every transfer should go to the same destination, leave `transfer_to` out of the schema and configure the default destination in the tool settings.

    4. **Expected Action**: Select the transfer call action. In API payloads, this is `executionMethod: "transfer_call"`.

    5. **Transfer destination**: Set the default target as `tool.transfer_to`.
       * Example phone number: `+15551234567`
       * Example SIP URI: `sip:support@pbx.example.com`

    6. **Post-transfer action**: Set `tool.post_transfer_action` to `end_call` or `resume_ai`.
       * `end_call` ends the AI leg after dispatching the transfer.
       * `resume_ai` resumes the assistant after the transferred leg ends, only where the channel supports bridge transfer.
  </Step>

  <Step title="Save Configuration">
    After configuring the tool, click **Configure Tool** to save your changes.
  </Step>
</Steps>

## Tool definition

When creating the tool through the API, use `transfer_call` as both the tool name and execution method unless you need a different model-facing name.

```json theme={null}
{
  "name": "transfer_call",
  "description": "Transfer the caller to a human support agent after confirming they want to be transferred.",
  "executionMethod": "transfer_call",
  "fields": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "transfer_to": {
        "type": "string",
        "description": "Phone number or SIP URI to transfer the call to."
      },
      "transfer_message": {
        "type": "string",
        "description": "Short message to say before transferring."
      },
      "transfer_delay": {
        "type": "number",
        "description": "Delay in milliseconds before dispatching the transfer."
      },
      "post_transfer_action": {
        "type": "string",
        "enum": ["end_call", "resume_ai"]
      }
    },
    "required": []
  },
  "executionOptions": [
    {
      "key": "tool.transfer_to",
      "value": "+15551234567"
    },
    {
      "key": "tool.post_transfer_action",
      "value": "end_call"
    }
  ]
}
```

## Arguments

The tool has two layers of configuration:

* **Execution options** set defaults for the tool when it is created.
* **Fields** define arguments the model can provide when it calls the tool.

### Execution options

| Option                      | Required | Description                                                    |
| --------------------------- | -------- | -------------------------------------------------------------- |
| `tool.transfer_to`          | Required | Default destination phone number or SIP URI.                   |
| `tool.transfer_message`     | Optional | Default message injected before the transfer is dispatched.    |
| `tool.transfer_delay`       | Optional | Default delay in milliseconds before dispatching the transfer. |
| `tool.post_transfer_action` | Optional | `end_call` or `resume_ai`. Defaults to `end_call`.             |

### Call arguments

| Argument               | Required                                             | Description                                                                                                    |
| ---------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `transfer_to`          | Required in tool options, optional in call arguments | Destination phone number or SIP URI. If the model provides this argument, it overrides the configured default. |
| `transfer_message`     | Optional                                             | Message injected before the transfer is dispatched.                                                            |
| `transfer_delay`       | Optional                                             | Delay in milliseconds before dispatching the transfer.                                                         |
| `post_transfer_action` | Optional                                             | `end_call` or `resume_ai`. Defaults to `end_call`.                                                             |

To provide multiple candidate targets, join them with `<|||>` in `transfer_to`. Channels that support only one-way transfer use the first target and ignore the rest.

## Provider behavior

Transfer support depends on the active phone channel:

| Channel                                             | Behavior                                                                                           |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Twilio                                              | Dispatches a one-way transfer with the first `transfer_to` target. The AI leg ends after dispatch. |
| Asterisk WebSocket / ARI                            | Dispatches a one-way redirect with the first `transfer_to` target. The AI leg ends after dispatch. |
| SIP                                                 | Starts bridge transfer mode and can use `post_transfer_action`.                                    |
| Vonage, Exotel, Telnyx, Vobiz, Asterisk AudioSocket | Returns a failed tool result because live transfer is not supported on those streams.              |

<Warning>
  Test transfer behavior on the same telephony provider you use in production. Unsupported channels return a failed tool result instead of silently transferring the call.
</Warning>

## Using the Transfer Call Tool

Once configured, your assistant can use the Transfer Call Tool when appropriate. The process typically follows these steps:

1. The assistant determines that a human or external destination should take over.
2. It says any configured transfer message or model-provided `transfer_message`.
3. It calls the Transfer Call Tool.
4. Rapida dispatches the channel-level transfer action and records the tool result.

## Best Practices

* Ask for confirmation before transferring unless your use case requires immediate escalation.
* Keep the transfer message short so the caller knows what is happening.
* Use a fixed `tool.transfer_to` for common queues and expose `transfer_to` only when the assistant must choose between destinations.
* Use `end_call` unless you have verified that your channel supports `resume_ai`.


# Voice Activity Detection (VAD)
Source: https://doc.rapida.ai/assistants/voice-activity-detection

Understand VAD providers, their parameters, and how to choose the right one for your voice AI assistant.

Voice Activity Detection (VAD) determines when a caller is speaking and when they are silent. It is part of Listen configuration — audio flows through VAD before reaching STT or End of Speech. A well-tuned VAD prevents background noise from triggering transcription, enables barge-in (interrupting the assistant mid-sentence), and feeds the End of Speech detector with speech activity signals.

All VAD providers in Rapida process **16 kHz LINEAR16 mono** audio and run locally — no network calls, no API keys, no added latency.

<Warning>
  **Deprecation notice:** TEN VAD is being deprecated due to a licensing issue. Do not use it for new assistants.
</Warning>

```mermaid theme={null}
flowchart LR
    A["Caller Audio\n16kHz LINEAR16"] --> B["VAD\nSpeech detection"]
    B -->|Speech detected| C["STT\nTranscription"]
    B -->|Activity signal| D["EOS\nSilence timer reset"]
    B -->|Speech onset| E["Interruption\nStop assistant TTS"]
```

***

## Providers

Rapida supports three VAD providers. Each shares the same three configuration parameters but uses a different detection model and approach.

| Provider                        | Description                                                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Silero VAD](#silero-vad)**   | The default. Lightweight ONNX model (\~2 MB) with strong accuracy across languages and noise conditions. Best general-purpose choice.                                        |
| **[TEN VAD](#ten-vad)**         | TEN Framework library with fixed 16 ms frame hops. Slightly lower latency per frame than Silero. Good for latency-critical deployments.                                      |
| **[FireRed VAD](#firered-vad)** | DFSMN streaming model with Kaldi-compatible fbank features and a 4-state postprocessor. Higher accuracy on noisy or overlapping speech at the cost of slightly more compute. |

***

## Silero VAD

[Silero VAD](https://github.com/snakers4/silero-vad) is a pre-trained ONNX model developed by the Silero team. It is one of the most widely adopted open-source VAD models, used in production by projects like Pipecat, LiveKit, and dozens of voice AI platforms.

**Why choose Silero VAD:**

* Battle-tested in production across thousands of voice applications
* Small model size (\~2 MB ONNX) with fast inference
* Strong accuracy across languages — trained on over 100 languages
* Works well in both clean and moderately noisy environments
* Default provider in Rapida — zero configuration needed to get started

**When to use:** Most deployments. If you have no specific reason to change, Silero is the right default.

### Parameters

| Parameter     | Config Key                  | Default | Range       | Description                                                                                                                                        |
| ------------- | --------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confidence    | `microphone.vad.confidence` | `0.7`   | 0.05 – 0.95 | Speech probability threshold. Each VAD frame produces a probability score between 0 and 1. Frames at or above this value are classified as speech. |
| Start Seconds | `microphone.vad.start_secs` | `0.2`   | 0 – 2       | Continuous speech duration before confirming speech onset and triggering an interruption.                                                          |
| Stop Seconds  | `microphone.vad.stop_secs`  | `0.2`   | 0 – 2       | Continuous non-speech duration before ending the active speech segment.                                                                            |

<Tip>
  **Confidence tuning guide:**

  * **0.3 – 0.4** — Very sensitive. Use only in extremely quiet, controlled environments. Will pick up breathing, lip smacks, and faint background sounds.
  * **0.5 – 0.6** — Balanced for clean audio.
  * **0.7 – 0.8** — Strict. This is the default range and reduces false triggers in typical phone and web audio.
  * **0.9 – 0.95** — Very strict. Only loud, clear speech triggers detection. Risk of missing normal conversational speech.
</Tip>

***

## TEN VAD

TEN VAD is part of the [TEN Framework](https://github.com/TEN-framework/ten-vad), an open-source real-time communication framework. It uses a native C library for frame-level speech probability scoring.

**Why choose TEN VAD:**

* Fixed 256-sample hop size (16 ms at 16 kHz) provides consistent, predictable frame timing
* Native C implementation — lower per-frame overhead than ONNX inference
* Lightweight with no model file to load from disk
* Good choice when you want the lowest possible per-frame processing time

**When to use:** Latency-critical deployments where every millisecond matters, or when you want a non-ONNX alternative. TEN VAD processes frames slightly faster than Silero because it avoids the ONNX runtime overhead, though the practical difference in end-to-end latency is small (single-digit milliseconds).

### Parameters

| Parameter     | Config Key                  | Default | Range | Description                                                                                                      |
| ------------- | --------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------- |
| Confidence    | `microphone.vad.confidence` | `0.7`   | 0 – 1 | Speech probability threshold. Same semantics as Silero — frames at or above this value are classified as speech. |
| Start Seconds | `microphone.vad.start_secs` | `0.2`   | 0 – 2 | Continuous speech duration before confirming speech onset.                                                       |
| Stop Seconds  | `microphone.vad.stop_secs`  | `0.2`   | 0 – 2 | Continuous non-speech duration before ending a speech segment.                                                   |

***

## FireRed VAD

[FireRed VAD](https://github.com/FireRedTeam/FireRedASR) is a DFSMN (Deep Feed-forward Sequential Memory Network) streaming model developed by the FireRed team at Ant Group. It uses Kaldi-compatible fbank feature extraction and CMVN normalization, with a sophisticated 4-state postprocessor for speech boundary detection.

**Why choose FireRed VAD:**

* Uses a 4-state machine (Silence → Possible Speech → Speech → Possible Silence) for more precise speech boundary detection
* Probability smoothing via a moving average window reduces jitter from frame-to-frame noise
* Better at handling overlapping speech and noisy environments than simpler threshold-based approaches
* Designed for streaming — processes 25 ms frames with 10 ms shifts for fine-grained detection

**When to use:** Noisy environments, call centre deployments, or scenarios where precise speech boundary detection matters more than raw speed. FireRed VAD's postprocessor is more sophisticated than Silero's or TEN's, which makes it better at avoiding false triggers in challenging audio conditions.

### Parameters

| Parameter     | Config Key                  | Default | Range | Description                                                                                                                                                                                    |
| ------------- | --------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confidence    | `microphone.vad.confidence` | `0.7`   | 0 – 1 | Probability threshold for speech detection. Applied after smoothing — the postprocessor uses a moving average window (size 5) to smooth raw probabilities before comparing against this value. |
| Start Seconds | `microphone.vad.start_secs` | `0.2`   | 0 – 2 | Continuous speech duration before confirming speech onset. Internally converted to FireRed's 10 ms postprocessor frames.                                                                       |
| Stop Seconds  | `microphone.vad.stop_secs`  | `0.2`   | 0 – 2 | Continuous non-speech duration before ending a speech segment. Internally converted to FireRed's 10 ms postprocessor frames.                                                                   |

<Info>
  FireRed VAD's postprocessor pads speech start by 5 frames (50 ms) to capture the onset of the utterance that triggered detection. The max speech frame limit is 2000 frames (20 seconds) — after which a forced speech end is emitted.
</Info>

***

## Choosing a provider

| Criteria             | Silero VAD        | TEN VAD                        | FireRed VAD        |
| -------------------- | ----------------- | ------------------------------ | ------------------ |
| **Model size**       | \~2 MB ONNX       | No model file (native library) | \~5 MB ONNX        |
| **Init time**        | Fast (\~10–30 ms) | Very fast (\~5 ms)             | Fast (\~10–30 ms)  |
| **Accuracy**         | High              | Good                           | High               |
| **Noise robustness** | Good              | Moderate                       | Best               |
| **Languages**        | 100+              | Language-agnostic              | Language-agnostic  |
| **Best for**         | General purpose   | Latency-critical               | Noisy environments |

<Tip>
  **Start with Silero VAD** (the default). Switch to FireRed VAD if you're seeing false triggers from background noise, or to TEN VAD if you're optimizing for the absolute lowest processing overhead.
</Tip>

***

## How VAD parameters affect the conversation

### Start Seconds — barge-in sensitivity

The `start_secs` parameter controls how quickly the assistant detects that a caller has started speaking and triggers a **barge-in** (interrupting assistant speech).

* **Lower values (0.05–0.1 s):** The assistant stops speaking quickly when the caller makes sound. Good for fast-paced IVR-style interactions. Risk: short sounds like coughs or "um" trigger interruption.
* **Default (0.2 s):** Requires about 200 ms of sustained speech before interrupting the assistant. Filters out most accidental sounds.
* **Higher values (0.3–0.5 s):** The assistant only stops when the caller has clearly started a full utterance. Good for avoiding false interruptions during one-way information delivery. Risk: the caller has to speak longer before the assistant stops.

### Stop Seconds — speech segment boundary

The `stop_secs` parameter controls how long the VAD waits in silence before considering a speech segment finished.

* **Lower values (0.05–0.1 s):** Speech segments are split at short pauses. Words spoken with natural gaps between them may be split into multiple segments.
* **Default (0.2 s):** Covers typical intra-sentence pauses. Most natural speech is captured as a single continuous segment.
* **Higher values (0.3–0.5 s):** Only longer pauses end a segment. Good for speakers who pause frequently mid-sentence.

<Warning>
  VAD stop seconds are different from End of Speech timeout. VAD determines **speech segment boundaries** (is the caller actively making sound right now?). End of Speech determines **turn boundaries** (has the caller finished their complete thought?). Both work together — VAD feeds activity signals to the EOS detector.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="End of Speech Detection" icon="clock" href="/assistants/end-of-speech">
    Configure how the assistant detects when a caller has finished their turn.
  </Card>

  <Card title="Create an Assistant" icon="plus" href="/assistants/create-assistant">
    Set up VAD as part of Listen configuration.
  </Card>
</CardGroup>


# Setting Up Webhooks
Source: https://doc.rapida.ai/assistants/webhook/create-webhook

Configure webhooks to receive call, conversation, and WebRTC events

This guide explains how to configure webhooks for an assistant.

Rapida provides webhooks that allow you to receive data generated during the call, WebRTC media, and assistant lifecycle. Webhooks can be triggered by call events such as `call.received`, `call.ringing`, and `call.ended`, WebRTC events such as `webrtc.connected`, `webrtc.reconnecting`, and `webrtc.failed`, or conversation events such as:

1. `conversation.begin`
2. `conversation.resume`
3. `conversation.completed`
4. `conversation.error`

Webhooks enable you to integrate assistant data with external systems, analyze conversations, and create custom workflows.

<Steps>
  <Step title="Access webhooks">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Webhooks".
    5. Click **Create new webhook** to begin configuration.

       <img alt="Access Webhooks" />
  </Step>

  <Step title="Select trigger events">
    <Frame>
      <img alt="Webhook event selection in Rapida" />

      <img alt="Webhook event selection in Rapida" />
    </Frame>

    Choose which call, WebRTC, and conversation events should trigger your webhook.

    **Call events**

    * **Call.Received**: Sends `call.received` when an inbound call reaches the assistant
    * **Call.Ringing**: Sends `call.ringing` when an outbound call is ringing
    * **Call.ProviderAnswered**: Sends `call.provider_answered` when the provider answers
    * **Call.OutboundRequested**: Sends `call.outbound_requested` when an outbound call is requested
    * **Call.OutboundDispatched**: Sends `call.outbound_dispatched` after the provider request is sent
    * **Call.OutboundDispatchFailed**: Sends `call.outbound_dispatch_failed` when the provider request fails
    * **Call.Started**: Sends `call.started` when the call media session starts
    * **Call.Hangup**: Sends `call.hangup` when a hangup signal is received
    * **Call.Ended**: Sends `call.ended` when the call session finishes
    * **Call.Failed**: Sends `call.failed` when the call fails
    * **Call.Cancelled**: Sends `call.cancelled` when an outbound call is cancelled before connect

    **WebRTC events**

    * **WebRTC.Connected**: Sends `webrtc.connected` when the WebRTC media connection is established
    * **WebRTC.AudioTrackReceived**: Sends `webrtc.audio_track_received` when the remote WebRTC audio track is received
    * **WebRTC.Reconnecting**: Sends `webrtc.reconnecting` when the WebRTC media connection starts recovery
    * **WebRTC.Failed**: Sends `webrtc.failed` when the WebRTC media connection fails
    * **WebRTC.Disconnected**: Sends `webrtc.disconnected` when the WebRTC media connection disconnects

    **Conversation events**

    * **Conversation.Begin**: Sends `conversation.begin` when a new conversation is initialized
    * **Conversation.Resume**: Sends `conversation.resume` when an existing conversation is resumed
    * **Conversation.Completed**: Sends `conversation.completed` after finalization and post-call analysis
    * **Conversation.Error**: Sends `conversation.error` when a conversation encounters an unrecoverable error

    You can select multiple events depending on your use case.
  </Step>

  <Step title="Configure delivery">
    <Frame>
      <img alt="Webhook delivery configuration in Rapida" />

      <img alt="Webhook delivery configuration in Rapida" />
    </Frame>

    Configure where Rapida sends the webhook request:

    * **Method**: Select `POST`, `PUT`, or `PATCH`.
    * **Server URL**: Enter the endpoint that receives webhook requests.
    * **Description**: Add an optional note for your team.
    * **Headers**: Add authentication headers or integration-specific headers.
    * **Retry**: Choose retry status entries and the maximum retry count.
    * **Timeout**: Set how long Rapida waits for your endpoint to respond.
    * **Priority**: Set execution order when multiple webhooks trigger at the same time.
  </Step>

  <Step title="Save the webhook">
    Review your webhook configuration and click **Configure webhook**.

    Rapida sends the standard webhook payload for each selected event. Custom request body mapping is not required.

    Your webhook is now configured and will be triggered during the selected events.
  </Step>
</Steps>

## Webhook payload structure

When triggered, your webhook receives a JSON payload with an `event` field and event-specific `data`. Call events include call-specific values such as provider, direction, call status, context ID, channel UUID, failure reason, or duration when available. WebRTC events include media-session values such as `session_id`, `media_session_id`, `codec`, `ice_latency_ms`, `peer_connection_state`, `reason`, and recovery counters when available.

The default `conversation.completed` payload includes the transcript, metadata, metrics, and any successful post-call analysis output:

```json theme={null}
{
  "event": "conversation.completed",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "reason": "conversation_completed",
    "status": "completed",
    "messages": [
      {
        "id": "msg-user-1",
        "role": "user",
        "content": "hello"
      },
      {
        "id": "msg-assistant-1",
        "role": "assistant",
        "content": "Hi there. How can I help?"
      }
    ],
    "metadata": {
      "customer_id": "cus_123",
      "analysis.conversation_summary": {
        "sentiment": "positive",
        "summary": "The user asked about account setup."
      }
    },
    "metrics": [
      {
        "name": "conversation_status",
        "value": "COMPLETE",
        "description": "Status of current conversation"
      }
    ]
  }
}
```

<Note>
  Analysis output is only available on `conversation.completed`. If an analysis endpoint fails, Rapida still sends the completed webhook. The failed analysis result is omitted from `data.metadata`.
</Note>


# Overview
Source: https://doc.rapida.ai/assistants/webhook/overview

Configure webhooks to receive call, conversation, and WebRTC events

Webhooks send call, conversation, and WebRTC events from Rapida to your HTTP endpoint. Use them to sync call status, media state, conversation state, transcripts, metadata, metrics, and post-call analysis results with your own systems.

<Frame>
  <img alt="Webhook event selection in Rapida" />

  <img alt="Webhook event selection in Rapida" />
</Frame>

## What are webhooks?

Webhooks are automated HTTP requests sent when a call, WebRTC media session, or assistant conversation reaches a configured event. They enable you to:

* Receive real-time updates about call, media, and conversation status
* Collect conversation data for analysis or storage
* Trigger actions in external systems based on call, WebRTC, or conversation events

## Events

### Call events

| Event                           | When it is sent                                           |
| ------------------------------- | --------------------------------------------------------- |
| `call.received`                 | An inbound call reaches the assistant.                    |
| `call.ringing`                  | An outbound call is ringing.                              |
| `call.provider_answered`        | The telephony provider answers the call.                  |
| `call.outbound_requested`       | An outbound call is requested.                            |
| `call.outbound_dispatched`      | The outbound call request is sent to the provider.        |
| `call.outbound_dispatch_failed` | The outbound call request cannot be sent to the provider. |
| `call.started`                  | The call media session starts.                            |
| `call.hangup`                   | A hangup signal is received.                              |
| `call.ended`                    | The call session finishes.                                |
| `call.failed`                   | The call fails.                                           |
| `call.cancelled`                | An outbound call is cancelled before connection.          |

### WebRTC events

| Event                         | When it is sent                                               | Payload notes                                                                                                                      |
| ----------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `webrtc.connected`            | The WebRTC media connection is established.                   | Includes `session_id`, `media_session_id`, `ice_latency_ms`, and `peer_connection_state`.                                          |
| `webrtc.audio_track_received` | The remote WebRTC audio track is received.                    | Includes `session_id`, `media_session_id`, and negotiated `codec`.                                                                 |
| `webrtc.reconnecting`         | The WebRTC media connection starts recovery.                  | Includes `type`, `session_id`, `media_session_id`, `reason`, `restart_attempt`, and `restart_limit`.                               |
| `webrtc.failed`               | The WebRTC media connection fails or falls back to text mode. | Includes failure `type`, `session_id`, `reason`, and optional `media_session_id`, `error`, `fallback`, or `peer_connection_state`. |
| `webrtc.disconnected`         | The WebRTC media connection disconnects or closes.            | Includes `session_id`, `media_session_id`, `reason`, and optional `type` or `peer_connection_state`.                               |

### Conversation events

| Event                    | When it is sent                                            | Payload notes                                                                                                                             |
| ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `conversation.begin`     | A new conversation is initialized.                         | Includes assistant ID, conversation ID, source, identifier, and `is_new`.                                                                 |
| `conversation.resume`    | An existing conversation is resumed.                       | Includes assistant ID, conversation ID, source, identifier, and message count.                                                            |
| `conversation.completed` | The conversation finalization flow completes successfully. | Post-call analysis runs before this webhook is recorded, so analysis output is included in `data.metadata` as `analysis.<analysis_name>`. |
| `conversation.error`     | The conversation hits an unrecoverable error.              | Includes assistant and conversation IDs when available, plus the error reason and message.                                                |

## Payload shape

All webhook requests are sent as JSON. The top-level envelope is consistent across event types:

```json theme={null}
{
  "event": "call.started",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "context_id": "ctx_123",
    "provider": "twilio",
    "direction": "inbound"
  }
}
```

The `conversation` object is included when the event is tied to a conversation. Event-specific fields are always inside `data`; `context_id` is not sent as a separate top-level field.

### Call payloads

Call event payloads include the available call lifecycle fields. Common keys are `provider`, `direction`, `caller`, `to`, `from`, `context_id`, `channel_uuid`, `status_event`, `provider_response`, `stage`, `reason`, `status`, `duration_ms`, `call_status`, `failure_class`, `failure_reason`, `disconnect_reason`, `provider_status_code`, `retryable`, and `error`.

```json theme={null}
{
  "event": "call.ended",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "context_id": "ctx_123",
    "provider": "twilio",
    "direction": "outbound",
    "caller": "+14155550100",
    "from": "+14155550199",
    "channel_uuid": "CA123",
    "reason": "talk_completed",
    "status": "COMPLETE",
    "duration_ms": 92840
  }
}
```

### WebRTC payloads

WebRTC events use the same envelope and include media-session fields in `data`.

```json theme={null}
{
  "event": "webrtc.connected",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "session_id": "2f2e6c8f-0b2d-4a5f-86da-7c7f3f7b3f92",
    "media_session_id": 3,
    "ice_latency_ms": 42,
    "peer_connection_state": "connected"
  }
}
```

For `webrtc.reconnecting`, `data.type` is usually `ice_restarting` or `media_session_restarting`. For `webrtc.failed`, `data.type` can include values such as `peer_failed`, `media_session_start_failed`, `media_session_restart_failed`, or `media_restart_limit_reached`.

### Conversation payloads

`conversation.begin` includes source and identifier context for a new conversation:

```json theme={null}
{
  "event": "conversation.begin",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "source": "phone-call",
    "is_new": "true",
    "identifier": "+14155550100"
  }
}
```

`conversation.resume` includes the same source and identifier context plus the current `message_count`.

The default `conversation.completed` payload has this structure:

```json theme={null}
{
  "event": "conversation.completed",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "reason": "conversation_completed",
    "status": "completed",
    "messages": [
      {
        "id": "msg-user-1",
        "role": "user",
        "content": "hello"
      },
      {
        "id": "msg-assistant-1",
        "role": "assistant",
        "content": "Hi there. How can I help?"
      }
    ],
    "metadata": {
      "customer_id": "cus_123",
      "analysis.conversation_summary": {
        "sentiment": "positive",
        "summary": "The user asked about account setup."
      }
    },
    "metrics": [
      {
        "name": "conversation_status",
        "value": "COMPLETE",
        "description": "Status of current conversation"
      }
    ]
  }
}
```

<Note>
  Analysis values are only available on `conversation.completed`. Call and WebRTC events do not include post-call analysis output. If an analysis endpoint fails, the completed webhook is still sent, but the failed analysis key is omitted from `data.metadata`.
</Note>

`conversation.error` includes the terminal error reason and message:

```json theme={null}
{
  "event": "conversation.error",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "reason": "DISCONNECTION_TYPE_ERROR",
    "message": "tts provider rejected credentials"
  }
}
```

## Configuration options

* **HTTP method**: Select the HTTP method used for delivery. `POST` is the default for most integrations.
* **Server URL**: Set the endpoint that receives webhook requests.
* **Headers**: Add authentication headers or any required integration headers.
* **Retry status entries**: Configure response status entries used by the delivery retry policy.
* **Retry count**: Set how many times Rapida should retry delivery for retryable failures.
* **Timeout**: Set how long Rapida should wait for your endpoint to respond.

## Use Cases

<CardGroup>
  <Card title="Real-time Monitoring" icon="trending-up">
    Set up webhooks to receive instant notifications about call, media, and conversation starts, completions, or failures. This allows you to monitor assistant performance and user engagement in real time.
  </Card>

  <Card title="Data Analysis" icon="search">
    Collect conversation data and analysis results through webhooks to feed into your analytics pipeline. This can help you gain insights into user behavior, common queries, and assistant effectiveness.
  </Card>

  <Card title="CRM Integration" icon="users">
    Use webhooks to automatically update customer records in your CRM system based
    on conversation outcomes. This ensures your customer data stays current
    without manual intervention.
  </Card>

  <Card title="Automated Workflows" icon="settings-2">
    Trigger automated actions in your systems based on specific conversation
    events or outcomes. For example, create support tickets, send follow-up
    emails, or update inventory based on user interactions.
  </Card>

  <Card title="Conversation Logging" icon="book">
    Maintain a comprehensive log of all assistant conversations by capturing
    webhook data. This can be crucial for compliance, training, and quality
    assurance purposes.
  </Card>

  <Card title="Multi-channel Support" icon="messages-square">
    Integrate webhook data with your omnichannel support system to provide seamless customer experiences across various platforms and touchpoints.
  </Card>
</CardGroup>


# Update Webhook
Source: https://doc.rapida.ai/assistants/webhook/update-webhook

Configure webhooks to receive call, conversation, and WebRTC events

This guide explains how to update webhook settings for an assistant.

Rapida provides webhooks that allow you to receive data generated during the call, WebRTC media, and assistant lifecycle. Webhooks can be triggered by call events such as `call.received`, `call.ringing`, and `call.ended`, WebRTC events such as `webrtc.connected`, `webrtc.reconnecting`, and `webrtc.failed`, or conversation events such as:

1. `conversation.begin`
2. `conversation.resume`
3. `conversation.completed`
4. `conversation.error`

Webhooks enable you to integrate assistant data with external systems, analyze conversations, and create custom workflows.

<Steps>
  <Step title="Access webhooks">
    1. Go to the Assistants section in the main navigation menu.
    2. Select the assistant you want to configure.
    3. Click "Configure assistant" in the top right corner.
    4. Select "Webhooks".
    5. Select the webhook you want to edit.

       <img alt="Access Webhooks" />
  </Step>

  <Step title="Update trigger events">
    <Frame>
      <img alt="Webhook event selection in Rapida" />

      <img alt="Webhook event selection in Rapida" />
    </Frame>

    Choose which call, WebRTC, and conversation events should trigger your webhook.

    **Call events**

    * **Call.Received**: Sends `call.received` when an inbound call reaches the assistant
    * **Call.Ringing**: Sends `call.ringing` when an outbound call is ringing
    * **Call.ProviderAnswered**: Sends `call.provider_answered` when the provider answers
    * **Call.OutboundRequested**: Sends `call.outbound_requested` when an outbound call is requested
    * **Call.OutboundDispatched**: Sends `call.outbound_dispatched` after the provider request is sent
    * **Call.OutboundDispatchFailed**: Sends `call.outbound_dispatch_failed` when the provider request fails
    * **Call.Started**: Sends `call.started` when the call media session starts
    * **Call.Hangup**: Sends `call.hangup` when a hangup signal is received
    * **Call.Ended**: Sends `call.ended` when the call session finishes
    * **Call.Failed**: Sends `call.failed` when the call fails
    * **Call.Cancelled**: Sends `call.cancelled` when an outbound call is cancelled before connect

    **WebRTC events**

    * **WebRTC.Connected**: Sends `webrtc.connected` when the WebRTC media connection is established
    * **WebRTC.AudioTrackReceived**: Sends `webrtc.audio_track_received` when the remote WebRTC audio track is received
    * **WebRTC.Reconnecting**: Sends `webrtc.reconnecting` when the WebRTC media connection starts recovery
    * **WebRTC.Failed**: Sends `webrtc.failed` when the WebRTC media connection fails
    * **WebRTC.Disconnected**: Sends `webrtc.disconnected` when the WebRTC media connection disconnects

    **Conversation events**

    * **Conversation.Begin**: Sends `conversation.begin` when a new conversation is initialized
    * **Conversation.Resume**: Sends `conversation.resume` when an existing conversation is resumed
    * **Conversation.Completed**: Sends `conversation.completed` after finalization and post-call analysis
    * **Conversation.Error**: Sends `conversation.error` when a conversation encounters an unrecoverable error

    You can select multiple events depending on your use case.
  </Step>

  <Step title="Update delivery">
    <Frame>
      <img alt="Webhook delivery configuration in Rapida" />

      <img alt="Webhook delivery configuration in Rapida" />
    </Frame>

    Update where Rapida sends the webhook request:

    * **Method**: Select `POST`, `PUT`, or `PATCH`.
    * **Server URL**: Enter the endpoint that receives webhook requests.
    * **Description**: Add an optional note for your team.
    * **Headers**: Add authentication headers or integration-specific headers.
    * **Retry**: Choose retry status entries and the maximum retry count.
    * **Timeout**: Set how long Rapida waits for your endpoint to respond.
    * **Priority**: Set execution order when multiple webhooks trigger at the same time.
  </Step>

  <Step title="Save changes">
    Review your webhook configuration and click **Update webhook**.

    Rapida sends the standard webhook payload for each selected event. Custom request body mapping is not required.
  </Step>
</Steps>

## Webhook payload structure

When triggered, your webhook receives a JSON payload with an `event` field and event-specific `data`. Call events include call-specific values such as provider, direction, call status, context ID, channel UUID, failure reason, or duration when available. WebRTC events include media-session values such as `session_id`, `media_session_id`, `codec`, `ice_latency_ms`, `peer_connection_state`, `reason`, and recovery counters when available.

The default `conversation.completed` payload includes the transcript, metadata, metrics, and any successful post-call analysis output:

```json theme={null}
{
  "event": "conversation.completed",
  "assistant": {
    "id": 2193965165215481856
  },
  "conversation": {
    "id": 2216964057603244032
  },
  "data": {
    "reason": "conversation_completed",
    "status": "completed",
    "messages": [
      {
        "id": "msg-user-1",
        "role": "user",
        "content": "hello"
      },
      {
        "id": "msg-assistant-1",
        "role": "assistant",
        "content": "Hi there. How can I help?"
      }
    ],
    "metadata": {
      "customer_id": "cus_123",
      "analysis.conversation_summary": {
        "sentiment": "positive",
        "summary": "The user asked about account setup."
      }
    },
    "metrics": [
      {
        "name": "conversation_status",
        "value": "COMPLETE",
        "description": "Status of current conversation"
      }
    ]
  }
}
```

<Note>
  Analysis output is only available on `conversation.completed`. If an analysis endpoint fails, Rapida still sends the completed webhook. The failed analysis result is omitted from `data.metadata`.
</Note>


# Rapida Credentials
Source: https://doc.rapida.ai/credential/rapida-credentials

Rapida offers two types of credentials: Project Credentials and Personal Tokens, each serving different purposes for authentication and access to Rapida platform services.

## Types of Rapida Credentials

Rapida provides two distinct types of credentials:

1. **Project Credentials**: These are project-specific keys used to authenticate and interact with the Rapida service for a particular project.
2. **Personal Tokens**: These are personal access tokens used to authenticate and interact with the Rapida service across all your projects.

## Project Credentials

Project Developer Keys are used to authenticate and interact with the Rapida service for a specific project. They are essential for SDK integration, widget implementation, and certain API calls.

### Accessing and Managing Project Credentials

<Steps>
  <Step title="Navigate to Project Credentials">
    Go to the "Integration > Project-Credential" page in your Rapida dashboard.
  </Step>

  <Step title="View Project Developer Keys">
    You'll see a list of existing Project Developer Keys, each labeled as a
    "Publishable Key" with its expiration date.
  </Step>

  <Step title="Create New Credential (Optional)">
    To generate a new key: - Look for the "Create new credential +" button at the
    top right of the page. - Click this button to automatically generate a new
    Publishable Key. - The new key will appear in the list with its expiration
    date.
  </Step>

  <Step title="Manage Existing Keys">
    For each Publishable Key, you can:

    * View the partially hidden key (click the eye icon to reveal)
    * Copy the key (click the copy icon)
    * See the expiration date
  </Step>
</Steps>

<img alt="Project Credentials Page" />

Note: These are project-specific keys. They are used to authenticate and interact with the Rapida service for this particular project, as stated in the information banner at the top of the page.

## Personal Tokens

Personal Tokens are used to authenticate and interact with the Rapida service across all your projects. They provide broader access and are typically used for administrative tasks or when working across multiple projects.

### Accessing Personal Tokens

<Steps>
  <Step title="Navigate to Personal Tokens">
    Go to the "Integration > Personal-Credential" page in your Rapida dashboard.
  </Step>

  <Step title="View Personal Token">
    You'll see your personal access token, which includes:

    * Authorization
    * X-Auth-Id
    * Project ID
  </Step>
</Steps>

<img alt="Personal Tokens Page" />

## Security Best Practices

* Keep all credentials (both Project Credentials and Personal Tokens) secure and never share them publicly.
* Use different Project Credentials for different environments (development, staging, production).
* Regularly rotate your credentials, especially if you suspect they may have been compromised.
* Use Personal Tokens cautiously, as they provide broader access across your projects.

By understanding and properly utilizing both types of Rapida credentials, you can ensure secure and efficient integration with the Rapida platform across various use cases and projects.


# Deployment Options
Source: https://doc.rapida.ai/deployments/deployment-options

Understanding how to deploy the Rapida Voice AI Platform

The Rapida Voice AI Platform supports multiple deployment options for teams that care about ownership, scale, and operational control. Agencies often need client-isolated deployments they can hand over. Enterprise teams often need governed environments that can scale without losing visibility. Rapida supports both.

Rapida Voice AI Platform supports two primary deployment modes:

* **Rapida Managed**: Fully managed platform service hosted on cloud infrastructure
* **Self-Hosting**: Self-managed deployment on your own infrastructure (EC2, Docker Kubernetes, etc.)

## Rapida Managed

Rapida Managed is a fully-managed, globally distributed Rapida deployment for teams that want enterprise rollout speed without operating the platform themselves. You keep the APIs, SDKs, and product surface while Rapida handles deployment, scaling, and maintenance.

* **Zero Infrastructure Management**: No need to manage servers, containers, or scaling
* **Automatic Scaling**: Built-in load balancing and auto-scaling capabilities
* **High Reliability**: Enterprise infrastructure with automatic failover
* **Managed Updates**: Automatic security patches and feature upgrades
* **Regional Deployment**: Choose from multiple global regions to optimize latency
* **Built-in Monitoring**: Integrated metrics, logging, and health monitoring

Best for: Teams that want to move fast, plus agencies and enterprise groups that need scale before they need full infrastructure ownership.

## Self-Hosting (EC2, Docker, or Custom Infrastructure)

Self-hosting gives you full ownership of the runtime. This is the preferred path for agencies that need client-controlled environments and enterprise teams with strict data, networking, or governance requirements. When self-hosting:

* **Full Control**: Complete control over hardware, networking, and configurations
* **Client and Tenant Isolation**: Keep client programs, business units, or environments separated on your terms
* **Custom Integrations**: Ability to integrate with existing infrastructure and tools
* **Data Localization**: Maximum data security for high-compliance environments
* **Custom Resource Allocation**: Optimize for your specific performance requirements
* **Custom Scaling**: Implement your own scaling strategies and resource management

Best for: Agencies delivering client-owned deployments and enterprise platform teams with strict security, procurement, or compliance requirements.

## Why Choose Rapida Managed?

* **Zero operational overhead**: No need to manage servers, scaling, or infrastructure.
* **Global edge network**: Users connect to the closest server for minimal latency.
* **Unlimited scale**: Support for high volume of concurrent calls with our distributed architecture.
* **Enterprise-grade reliability**: 99.9% uptime guarantee with redundant infrastructure.
* **Comprehensive analytics**: Monitor usage, performance, and quality metrics through the Rapida dashboard.
* **Same APIs and SDKs**: Use the exact same code whether you're on Rapida Managed or self-hosted.

Rapida Managed runs the same open-source servers that you can find on GitHub. It provides the same APIs and supports all of the same SDKs. An open-source user can migrate to Rapida Managed, and a Rapida Managed customer can switch to self-hosted at any moment. As far as your code is concerned, the only difference is the URL that it connects to.

## Comparing Rapida Managed to Self-hosted

When building with Rapida, you can either self-host the open-source server or use the managed Rapida service:

| Feature                     | SELF-HOSTED                                                      | RAPIDA MANAGED                                       |
| --------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
| Runtime features            | Full support                                                     | Full support                                         |
| Voice recording & streaming | Full support                                                     | Full support                                         |
| Voice agent framework       | Full support                                                     | Full support                                         |
| Best fit                    | Client-owned deployments, strict control, private infrastructure | Fast rollout with managed operations                 |
| Who manages it              | You                                                              | Rapida                                               |
| Control boundary            | You own infra, keys, networking, and data path                   | Rapida operates the platform with dedicated controls |
| Architecture                | Single-node deployment                                           | Distributed mesh network                             |
| Connection model            | Direct connection to your server                                 | Each user connects to the closest server             |
| Max concurrent calls        | Depends on your hardware                                         | No limit (auto-scaling)                              |
| Analytics & telemetry       | Comprehensive dashboard                                          | Comprehensive dashboard                              |
| Uptime guarantees           | N/A                                                              | 99.9%                                                |
| Security & compliance       | Self-managed                                                     | Enterprise-grade, SOC 2 compliant                    |


# Rapida Fully Managed Deployment
Source: https://doc.rapida.ai/deployments/fully-managed

Enterprise-managed deployment for teams that need scale without owning the infrastructure

The Rapida Fully Managed option is for teams that need enterprise reliability and fast rollout without owning the infrastructure. It is a strong fit for agencies launching multiple client programs quickly and enterprise teams that want to focus on assistants, not platform operations.

## Key Benefits

* **Zero Infrastructure Management**: No server provisioning, monitoring, or maintenance
* **Automatic Updates**: Always run the latest version with security patches and new features
* **Enterprise-grade SLAs**: 99.9% uptime guarantee with 24/7 monitoring
* **Dedicated Support**: Priority technical support from our engineering team
* **Flexible Scaling**: Resources automatically adjust based on your usage patterns
* **Regional Deployment Options**: Optimize latency and governance requirements across multiple regions

## When to Choose Fully Managed

The Fully Managed option is ideal for:

* Agencies that need to launch multiple client programs without building a platform team
* Enterprise teams without dedicated DevOps ownership
* Applications that need enterprise-grade reliability
* Projects requiring rapid time-to-market
* Companies focused on product delivery rather than infrastructure operations

## Get Started

To learn more about pricing, service level agreements, and deployment options for Rapida Fully Managed, please contact our solutions team:

**Contact: [prashant@rapida.ai](mailto:prashant@rapida.ai)**

Our team will work with you to understand your specific requirements and provide a tailored solution for your voice AI needs.


# Self hosted Deployment
Source: https://doc.rapida.ai/deployments/self-hosted

Deploy the Rapida Voice AI Platform on infrastructure your team or clients control

## Choose Your Deployment Mode

Rapida ships as two Docker Compose configurations. Self-hosted is the right starting point for agencies that need client ownership and enterprise teams that need scale, governance, and infrastructure control.

|                    | Voice Assistant Only                                                     | Voice + Knowledge Base                                                                     |
| ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **What it does**   | Build voice assistants that call LLMs directly on infrastructure you own | Everything in Voice Only, plus upload documents and answer questions from your own content |
| **Extra services** | —                                                                        | `document-api` (Python) + `opensearch`                                                     |
| **RAM**            | 4 GB minimum                                                             | 8–16 GB (OpenSearch is memory-intensive)                                                   |
| **Build command**  | `make build-all`                                                         | `make build-all-with-knowledge`                                                            |
| **Start command**  | `make up-all`                                                            | `make up-all-with-knowledge`                                                               |

<Tip>
  **Start with Voice Only.** You can add the knowledge base at any time by running `make up-all-with-knowledge` — no data is lost and your ownership model does not change.
</Tip>

***

## Quickstart

### Requirements

* [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Mac / Windows) or Docker Engine v20.10+ with Docker Compose v2.0+ (Linux)
* **Voice Only**: 4 GB RAM, 10 GB free disk
* **With Knowledge Base**: 8–16 GB RAM, 20 GB free disk

### Steps

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/rapidaai/voice-ai.git
    cd voice-ai
    ```
  </Step>

  <Step title="Create data directories">
    ```bash theme={null}
    make setup-local
    ```

    This creates `~/rapida-data/assets/db`, `~/rapida-data/assets/redis`, and `~/rapida-data/assets/opensearch` and sets the correct permissions.

    <Note>
      On macOS, `setup-local` calls `sudo setfacl` which requires the `acl` package. If it fails, create the directories manually:

      ```bash theme={null}
      mkdir -p ~/rapida-data/assets/{db,redis,opensearch}
      ```
    </Note>
  </Step>

  <Step title="Configure YAML files">
    Each service has a YAML config file under `docker/<service>/`. Edit them with your API keys and settings:

    ```
    docker/web-api/web.yml
    docker/assistant-api/assistant.yml
    docker/integration-api/integration.yml
    docker/endpoint-api/endpoint.yml
    ```

    This is where you define provider keys, networking, runtime behavior, and client- or environment-specific settings.

    See [Configuration](/opensource/configuration) for a full reference of all variables.
  </Step>

  <Step title="Build images">
    <Tabs>
      <Tab title="Voice Only (recommended)">
        ```bash theme={null}
        make build-all
        ```

        Builds: `web-api`, `assistant-api`, `integration-api`, `endpoint-api`, `ui`. Does **not** include `document-api` or `opensearch`.

        Initial build takes 10–25 minutes (the `assistant-api` uses CGO with the Azure Speech SDK).
      </Tab>

      <Tab title="With Knowledge Base">
        ```bash theme={null}
        make build-all-with-knowledge
        ```

        Builds everything above **plus** `document-api` (Python image). Requires 8–16 GB RAM.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start Rapida">
    <Tabs>
      <Tab title="Voice Only (recommended)">
        ```bash theme={null}
        make up-all
        ```

        Starts: `postgres`, `redis`, `web-api`, `assistant-api`, `integration-api`, `endpoint-api`, `ui`, `nginx`.
      </Tab>

      <Tab title="With Knowledge Base">
        ```bash theme={null}
        make up-all-with-knowledge
        ```

        Starts everything above **plus** `opensearch` and `document-api`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Open the dashboard">
    Navigate to **[http://localhost:3000](http://localhost:3000)** in your browser.

    Check container status with:

    ```bash theme={null}
    make status
    ```
  </Step>
</Steps>

***

## Common Issues

### Port conflicts

If you see *"port is already in use"*, another service on your machine is using one of Rapida's ports (5432, 6379, 9001, 9004, 9005, 9007, 8080, 3000). Stop the conflicting service or edit the port mapping in `docker-compose.yml`.

### Container name conflicts

Rapida containers use common names (`postgres`, `redis`, `opensearch`). If you run other projects with the same names, stop them first:

```bash theme={null}
docker stop postgres redis opensearch
docker rm postgres redis opensearch
```

### Out of memory

If containers are killed during startup (exit code 137), Docker does not have enough memory allocated.

* **Docker Desktop** → Settings → Resources → Memory: set to **8 GB** (Voice Only: 4 GB minimum)
* **Tip**: Stop all services before rebuilding — `make down-all` then `make build-all` — to avoid OOM during builds.

### `document-api` unhealthy on first boot

On first startup, `document-api` can take 30–60 seconds to connect to OpenSearch. If `make up-all-with-knowledge` exits with a dependency error, wait a moment and run it again:

```bash theme={null}
make up-all-with-knowledge
```

***

## Next Steps

* [Installation guide](/opensource/installation) — detailed Docker and manual setup
* [Overview](/opensource/overview) — architecture and service descriptions
* [Configuration](/opensource/configuration) — all environment variable references


# Create endpoint
Source: https://doc.rapida.ai/endpoint/create-endpoint

Endpoints allow you to integrate Large Language Models (LLMs) into your application, providing a powerful interface for AI-driven functionalities.

## Prerequisites

Before creating an endpoint, ensure that you have integrated the desired AI provider with Rapida. To set up integrations:

1. Navigate to the Integrations section in your Rapida dashboard.
2. Select the AI provider you want to integrate (e.g., OpenAI, Anthropic, Google AI).
3. Follow the provider-specific instructions to complete the integration.

For detailed instructions on setting up integrations, refer to the provider-specific documentation in the Integrations section:

* [OpenAI](/integrations/llm/openai)
* [Anthropic](/integrations/llm/anthropic)
* [Google AI](/integrations/llm/google-ai)
* [Cohere](/integrations/llm/cohere)
* [Azure OpenAI](/integrations/llm/azure-openai)

<Steps>
  <Step title="Choose Model">
    Select the LLM Provider you want to use for your endpoint. The interface shows various options.

    <Note>
      Each model may have different capabilities and pricing structures, so choose
      the one that best fits your needs.
    </Note>

    <img alt="Choose Model Interface" />
  </Step>

  <Step title="Select Provider Credential">
    Choose the appropriate credential for the selected provider from the dropdown
    menu. If you haven't set up credentials for this provider yet, you can: -
    Click the "+" button to add a new credential - Click the refresh button to
    update the list of available credentials

    <Note>
      Make sure you've already configured credentials for your chosen provider in
      the Integrations section.
    </Note>
  </Step>

  <Step title="Configure Model Settings">
    Depending on the chosen provider, configure various settings such as Frequency Penalty, Temperature, Top P, Max Completion Tokens, Response Format, and Stop Sequences by clicking on the settings icon next to the selected model.

    <img alt="Configure Model Settings" />
  </Step>

  <Step title="Set Up Instructions">
    Create a system message and user message template. Define the role or context for the AI, set up the structure for user inputs, and define custom arguments that can be dynamically inserted into your prompts.

    <img alt="Set Up Instructions" />
  </Step>

  <Step title="Define Endpoint Profile">
    Provide a unique name for your endpoint, a brief description of its purpose, and add relevant tags to categorize it.

    <img alt="Define Endpoint Profile" />
  </Step>
</Steps>

### Additional Notes

* New versions of the assistant will not be deployed automatically. Manual deployment is required to update the production version.
* You can add multiple messages to create more complex conversation flows.
* The interface allows for easy editing and rearranging of messages.

## Finalizing Your Endpoint

After configuring all settings, click the "Create endpoint" or "Configure instruction" button to finalize your endpoint creation. Your new endpoint will then be listed in the Hosted Endpoints dashboard, where you can monitor its status, run count, error rate, and other performance metrics.

By following these steps, you can create a custom endpoint that leverages powerful LLMs to enhance your application's capabilities.


# Create new version
Source: https://doc.rapida.ai/endpoint/create-new-version

Quick guide to updating your existing endpoint with a new version.

<Note>
  New versions require manual deployment to update the production version.
</Note>

## Step-by-Step Guide

<Steps>
  <Step title="Access Endpoint Settings">
    1. Go to Deployment section
    2. Select the endpoint to update
    3. Click "Create new version"
  </Step>

  <Step title="Modify Endpoint">
    * **Change Endpoint Definition**: Adjust model, instructions, variables
    * **Update Model Settings**: Fine-tune parameters (e.g., temperature, max tokens)
    * **Revise Instructions**: Edit system/user messages, modify arguments

      <img alt="Modify Endpoint Interface" />
  </Step>

  <Step title="Describe Changes">
    Enter a brief description of modifications in the "Change Description" field.

    <img alt="Modify Endpoint Interface" />
  </Step>

  <Step title="Manage Versions">
    * View "Version history"
    * Compare versions if needed
    * Deploy new version when ready

      <img alt="Version History Interface" />
  </Step>
</Steps>

## Best Practices

* Use clear change logs
* Test thoroughly before deployment
* Consider separate dev/prod endpoints
* Review performance metrics regularly


# Monitoring & debugging
Source: https://doc.rapida.ai/endpoint/monitor-endpoint-performance

The endpoint dashboard provides a detailed view of your deployment's performance and activity. Here's how to use it effectively for monitoring and debugging:

<img alt="Navigate to Knowledge" />

<AccordionGroup>
  <Accordion title="ID and Version">
    Each row represents a unique request, identified by an ID and version
    number. Use these to track specific invocations of your endpoint.
  </Accordion>

  <Accordion title="Source">
    Indicates the origin of the request (e.g., "Replicate App"). This helps you
    identify which integrations or applications are using your endpoint.
  </Accordion>

  <Accordion title="Status">
    Shows the current state of each request. "Complete" indicates successful
    processing. Monitor this column for any non-complete statuses that may
    require attention.
  </Accordion>

  <Accordion title="Performance Metrics">
    * Total Time Taken: The overall processing duration for each request. - LLM
      Total Token: The number of tokens processed by the language model. - LLM
      Time Taken: Time specifically spent on language model operations. Use these
      metrics to identify performance bottlenecks or unexpected behavior.
  </Accordion>

  <Accordion title="Created Date">
    The timestamp when the request was initiated. This helps in tracking the
    timeline of requests and identifying patterns over time.
  </Accordion>
</AccordionGroup>

### Detailed Request Information

When monitoring your endpoint performance, you can expand individual requests to access detailed information. This feature provides in-depth insights into each request, helping you analyze performance, troubleshoot issues, and understand how your endpoint is being used.

To view detailed information for a specific request:

1. Locate the request you want to examine in your monitoring dashboard.
2. Click on the request to expand its details.
3. You'll see a tabbed interface with the following sections:

#### Metrics

View detailed performance data for the request, including:

* Time taken to process the request
* LLM request ID
* Request status

Use this tab for in-depth performance analysis and to identify potential bottlenecks.

#### Metadata

Access additional context about the request. This information is helpful for understanding the request's parameters and overall configuration.

#### Options

Review the configuration settings used for this specific request. This tab is useful to ensure the endpoint was called with the expected options and to verify any custom settings applied.

#### Arguments

Examine the input parameters provided to the endpoint for this request. This tab is particularly useful for:

* Reproducing issues
* Understanding how your endpoint is being used in practice
* Verifying the correct inputs were sent to the endpoint

To navigate between these sections, simply click on the desired tab in the left sidebar. The main content area on the right will update to display the selected information.

By leveraging this detailed view, you can gain valuable insights into your endpoint's performance and usage patterns, enabling you to optimize your AI applications more effectively.

## Debugging Techniques

When investigating issues or optimizing performance:

1. **Analyze Trends**: Look for patterns in the Total Time Taken or LLM Time Taken across requests. Sudden increases may indicate performance degradation.

2. **Compare Versions**: Use the version history to identify if recent changes have impacted performance or reliability.

3. **Inspect Failures**: For any non-"Complete" statuses, expand the request details to examine metrics, options, and arguments for clues about what went wrong.

4. **Token Usage**: Monitor the LLM Total Token to ensure it aligns with expectations and to manage costs effectively.

5. **Source Analysis**: If issues are isolated to specific sources, it may indicate problems with particular integrations or client implementations.

## Advanced Monitoring

For more in-depth analysis:

<Card title="LLM Logs" icon="file-text">
  Access detailed logs of language model operations for advanced debugging.
  These logs provide insights into the internal workings of the LLM during
  request processing.
</Card>

<Card title="SDK & Integration" icon="code">
  Consult the SDK documentation for implementation details and best practices
  for client integration. Proper SDK usage can prevent many common issues and
  optimize endpoint interaction.
</Card>

By leveraging these dashboard features and following these debugging strategies, you can effectively monitor your endpoint's health, quickly identify and resolve issues, and ensure optimal performance.


# Overview
Source: https://doc.rapida.ai/endpoint/overview

Seamlessly integrate LLMs into your application with powerful, flexible endpoints

Rapida endpoints are the cornerstone of integrating Large Language Models (LLMs) into your application. They provide a robust, user-friendly interface between your code and advanced AI capabilities, enabling you to harness the power of LLMs with ease and flexibility.

<img alt="Rapida Endpoint Overview" />

## What are Rapida Endpoints?

Rapida endpoints are specialized access points that allow your application to interact with LLMs efficiently. They handle the complexities of LLM communication, letting you focus on building innovative features rather than managing infrastructure.

## Key Features and Benefits

<CardGroup>
  <Card title="Simplified Integration" icon="puzzle">
    Integrate LLM capabilities into your app with just a few lines of code,
    reducing development time and complexity.
  </Card>

  <Card title="Flexible Model Selection" icon="toggle-left">
    Easily switch between different LLM models without modifying your
    application code, future-proofing your AI integration.
  </Card>

  <Card title="Robust Prompt Management" icon="file-code">
    Version control and template your prompts for consistent, maintainable, and
    scalable LLM interactions.
  </Card>

  <Card title="Performance Optimization" icon="gauge">
    Benefit from built-in caching and request batching to improve response times
    and reduce costs.
  </Card>
</CardGroup>

## Common Use Cases

Rapida endpoints empower a wide range of AI-driven functionalities:

<CardGroup>
  <Card title="Intelligent Content Generation" icon="pen-tool">
    Create high-quality text, from articles to product descriptions, tailored to
    your specific needs.
  </Card>

  <Card title="Advanced Text Analysis" icon="bar-chart-2">
    Extract insights, sentiment, and key information from large volumes of text
    data.
  </Card>

  <Card title="Conversational AI" icon="message-circle">
    Build sophisticated chatbots and virtual assistants with natural language
    understanding.
  </Card>

  <Card title="Automated Summarization" icon="file-text">
    Generate concise summaries of lengthy documents or conversations.
  </Card>

  <Card title="Language Translation" icon="languages">
    Provide accurate, context-aware translations across multiple languages.
  </Card>
</CardGroup>

## Getting Started

To begin using Rapida endpoints in your project:

1. Sign up for a Rapida account and obtain your API key.
2. Choose the appropriate endpoint for your use case from our documentation.
3. Make your first API call using our easy-to-follow code examples.

Check out the [API Reference](/api-reference/installation) for SDK setup and a step-by-step tutorial.

## Best Practices

To maximize the effectiveness of Rapida endpoints:

* Use prompt templates to maintain consistency across your application.
* Implement proper error handling to manage rate limits and unexpected responses.
* Monitor your usage and optimize prompts for better performance and cost-efficiency.
* Regularly update to the latest endpoint versions for new features and improvements.

## Conclusion

Rapida endpoints provide a powerful, flexible, and user-friendly way to integrate cutting-edge LLM capabilities into your applications. By leveraging our robust infrastructure and intuitive API, you can focus on creating innovative AI-powered features that set your product apart. Start exploring the possibilities with Rapida endpoints today!


# Organizations
Source: https://doc.rapida.ai/governances/organization

Create and manage your organization — the top-level entity that owns all projects, billing, and members in Rapida.

An **Organization** is the top-level administrative entity in Rapida. It owns all projects, user memberships, and billing information. Every Rapida account belongs to exactly one organization.

## Organization Roles

| Role                    | Capabilities                                                                                 |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **Organization Admin**  | Create and archive projects, manage organization-wide settings, invite users, manage billing |
| **Organization Member** | Access projects they have been invited to; cannot create new projects                        |

Organization admins do not automatically have admin rights inside individual projects — project membership and roles are managed separately.

## Managing Your Organization

* **Settings**: Update organization name, logo, and contact details from the organization settings page.
* **Billing**: Manage your subscription plan and payment methods.
* **Users & Teams**: Invite members to the organization and assign them to projects. See [User Management](/workspace/user-management).
* **Projects**: Create isolated projects for different teams, products, or environments. See [Project Management](/workspace/project-management).

## Best Practices

* Use separate projects for development, staging, and production environments rather than a single project.
* Regularly audit organization membership and remove accounts that no longer need access.
* Assign the minimum necessary role to each member.


# Governance Overview
Source: https://doc.rapida.ai/governances/overview

Understand how organizations, projects, users, and roles are structured in the Rapida platform.

Rapida uses a two-level hierarchy to organize access and resources: **Organizations** at the top level, and **Projects** within each organization. Every user account belongs to an organization and can be a member of one or more projects within it.

## Hierarchy

```
Organization
└── Project A
│   ├── Assistants
│   ├── Endpoints
│   ├── Knowledge Bases
│   └── Members (with project roles)
└── Project B
    └── ...
```

## Key Concepts

<CardGroup>
  <Card title="Organizations" icon="building" href="/governances/organization">
    The top-level entity. An organization owns all projects, billing, and
    organization-wide members.
  </Card>

  <Card title="Projects" icon="folder" href="/governances/project">
    Isolated containers for assistants, endpoints, and knowledge bases. Each
    project has its own credentials and member roles.
  </Card>

  <Card title="Roles & Permissions" icon="shield-check" href="/governances/roles-and-permission">
    Fine-grained access control at the project level. A user can hold different
    roles across different projects.
  </Card>

  <Card title="Users & Teams" icon="users" href="/workspace/user-management">
    Invite team members to your organization or specific projects and assign
    them the appropriate role.
  </Card>
</CardGroup>

## Role Summary

| Role            | Scope   | Capabilities                                           |
| --------------- | ------- | ------------------------------------------------------ |
| **Super Admin** | Project | Full control — manage resources, settings, and members |
| **Admin**       | Project | Manage resources and invite collaborators              |
| **Member**      | Project | Create and use project resources                       |
| **Viewer**      | Project | Read-only access                                       |

Organization admins can create and archive projects but do not automatically inherit project-level admin rights.


# Projects
Source: https://doc.rapida.ai/governances/project

Projects are isolated workspaces within your organization — each with its own assistants, endpoints, knowledge bases, credentials, and team members.

A **Project** is an isolated workspace within your organization. Projects keep resources — assistants, endpoints, knowledge bases, and credentials — separated so different teams or environments don't interfere with each other.

## What Lives Inside a Project

* **Assistants**: Voice AI agents deployed on phone, web widget, or via API
* **LLM Endpoints**: Configured language model connections with prompt templates
* **Knowledge Bases**: Documents and data sources for RAG-powered responses
* **Credentials**: Project-scoped API keys used by SDKs and the web widget
* **Activity Logs**: Conversation, LLM, and webhook logs scoped to this project

## Project Credentials

Each project has its own set of **Publishable Keys** used to authenticate SDK calls and web widget embeds. These are scoped to the project and cannot be used to access resources in other projects. See [Credentials](/credential/rapida-credentials) for details.

## Creating a Project

See [Create a New Project](/workspace/create-new-project) for step-by-step instructions.

## Project Roles

Membership and permissions are set at the project level. A user can have different roles in different projects:

| Role            | Capabilities                              |
| --------------- | ----------------------------------------- |
| **Super Admin** | Full control over the project             |
| **Admin**       | Manage resources and invite collaborators |
| **Member**      | Create and use project resources          |
| **Viewer**      | Read-only access                          |

## Best Practices

* Create separate projects for `development`, `staging`, and `production`.
* Use descriptive project names that reflect the team or product they serve.
* Review project membership regularly and remove users who no longer need access.


# Roles & Permissions
Source: https://doc.rapida.ai/governances/roles-and-permission

Your team members access your organization and its projects using individual user accounts which is what you use to sign into RapidaAI. An account must be part of an organization but it does not need to be part of all projects in the organization. Each account will have a single organization role per organization and one project role for each project it is a part of. These roles can further limit what an account will have access to in RapidaAI.

## Invite Users

You can invite users users to an organization or to a project with specific role permissions.

## Invite Users to an Organization's Project

* Under "Organization", click Users & Teams and you will land on the Users tab.
* Click Invite Users. The “Invite New Users” box appears.
* Enter the email address of the user and select their Projects and Project Role.
* Click Add another user to invite additional users.
* Click Invite to complete the process.


# Anthropic
Source: https://doc.rapida.ai/integrations/llm/anthropic

Anthropic is an AI research company known for its advanced language models, including the Claude series.

## Getting Started

To integrate Anthropic with your Rapida application, follow these steps:

## Supported Models

Anthropic offers several advanced language models that can be used with this integration. Here's a table of the supported models:

| Model Name                 | Series   | Description                                         |
| -------------------------- | -------- | --------------------------------------------------- |
| claude-opus-4-20250514     | Claude 4 | Latest Claude 4 model with advanced capabilities    |
| claude-sonnet-4-20250514   | Claude 4 | Sonnet version of Claude 4 for specific use cases   |
| claude-3-7-sonnet-20250219 | Claude 3 | Claude 3.7 Sonnet model with improved performance   |
| claude-3-5-haiku-20241022  | Claude 3 | Claude 3.5 Haiku model for lightweight applications |
| claude-3-5-sonnet-20241022 | Claude 3 | Claude 3.5 Sonnet model for balanced performance    |

These models offer various capabilities and performance levels. Choose the appropriate model based on your specific use case and requirements.

## Prerequisites

* Go to the Anthropic platform at [https://www.anthropic.com](https://www.anthropic.com).
* Sign up or log in to your Anthropic account.
* Navigate to the API section.
* Generate your API key.
* Copy the API key (make sure to save it securely, as it won't be shown again).

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select a Provider">
    On the Integrations page, find the provider you want to set up credentials for. Each provider card shows a brief description and a "Connected" or "Setup Credential" button.

    Click the "Setup Credential" button for your chosen provider.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select Your Provider from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Key: Input the actual API key or credential for the provider
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your provider credential is now set up and ready to use with the integration system.


# Azure OpenAI
Source: https://doc.rapida.ai/integrations/llm/azure-openai

Azure OpenAI Service provides REST API access to OpenAI's powerful language models including the GPT-4 series.

## Getting Started

To integrate Azure OpenAI with your Rapida application, follow these steps:

## Supported Models

Azure OpenAI offers several advanced language models that can be used with this integration. Here's a table of some supported models:

| Model Name   | Series | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| gpt-4o       | GPT-4  | Latest GPT-4 model with advanced capabilities |
| gpt-4o-mini  | GPT-4  | Mini version of GPT-4 for specific use cases  |
| gpt-4.1-nano | GPT-4  | Nano version of GPT-4.1 for lightweight apps  |

Note: You can also enter your own deployment model name if you have custom deployments.

## Prerequisites

* Go to the Azure portal at [https://portal.azure.com](https://portal.azure.com).
* Sign up or log in to your Azure account.
* Create an Azure OpenAI resource.
* Navigate to the resource and find the "Keys and Endpoint" section.
* Copy the endpoint URL and one of the subscription keys (make sure to save them securely).

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select Azure OpenAI">
    On the Integrations page, find the Azure OpenAI provider card.

    Click the "Setup Credential" button for Azure OpenAI.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Azure OpenAI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Subscription Key: Input the subscription key from your Azure OpenAI resource
    4. Enter the Endpoint: Input the endpoint URL from your Azure OpenAI resource
    5. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Azure OpenAI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Azure OpenAI provider credential is now set up and ready to use with the integration system.


# AWS Bedrock
Source: https://doc.rapida.ai/integrations/llm/bedrock

AWS Bedrock provides a fully managed service that offers a choice of high-performing foundation models from leading AI companies through a single API.

## Getting Started

To integrate AWS Bedrock with your Rapida application, follow these steps:

## Supported Models

AWS Bedrock offers several advanced language models that can be used with this integration. Here's a table of some supported models:

| Model Name                    | Provider  | Description                                       |
| ----------------------------- | --------- | ------------------------------------------------- |
| ai21.jamba-instruct-v1:0      | AI21 Labs | Instruct model for various NLP tasks              |
| anthropic.claude-v2:1         | Anthropic | Latest Claude v2 model with advanced capabilities |
| anthropic.claude-v2           | Anthropic | Claude v2 model for general language tasks        |
| anthropic.claude-instant-v1   | Anthropic | Faster, more efficient Claude model               |
| anthropic.claude-instant-v1:2 | Anthropic | Updated version of Claude Instant                 |
| anthropic.claude-v2:0         | Anthropic | Initial release of Claude v2                      |

Note: AWS Bedrock may add or update models over time. Check the AWS Bedrock documentation for the most up-to-date list of available models.

## Prerequisites

* Have an AWS account with access to AWS Bedrock.
* Set up your AWS credentials and permissions to use Bedrock.
* Ensure you have the necessary IAM permissions to access Bedrock and its models.

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select AWS Bedrock">
    On the Integrations page, find the AWS Bedrock provider card.

    Click the "Setup Credential" button for AWS Bedrock.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "AWS Bedrock" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the AWS Access Key ID: Input your AWS access key ID
    4. Enter the AWS Secret Access Key: Input your AWS secret access key
    5. Select the AWS Region: Choose the region where you want to use Bedrock
    6. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    <img alt="View Provider Credential" />

    After setting up the credential, you can verify it's been added:

    1. The AWS Bedrock provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your AWS Bedrock provider credential is now set up and ready to use with the integration system.


# Cohere
Source: https://doc.rapida.ai/integrations/llm/cohere

Cohere is an AI company that provides large language models and NLP tools for developers and businesses.

## Getting Started

To integrate Cohere with your Rapida application, follow these steps:

## Supported Models

Cohere offers several advanced language models that can be used with this integration. Here's a table of the supported models:

| Model Name             | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| command-a-03-2025      | Latest Command model with advanced capabilities          |
| command-r7b-12-2024    | Specialized Command model for specific use cases         |
| command-r-plus-04-2024 | Enhanced Command model with improved performance         |
| command-r-plus         | Stable version of the enhanced Command model             |
| command-r-08-2024      | Command model optimized for August 2024                  |
| command-r-03-2024      | Command model optimized for March 2024                   |
| command-r              | Standard Command model for general use                   |
| command                | Original Command model                                   |
| command-nightly        | Nightly updated version of the Command model             |
| command-light          | Lightweight version of the Command model                 |
| command-light-nightly  | Nightly updated lightweight version of the Command model |

These models offer various capabilities and performance levels. Choose the appropriate model based on your specific use case and requirements.

## Prerequisites

* Go to the Cohere platform at [https://cohere.ai](https://cohere.ai).
* Sign up or log in to your Cohere account.
* Navigate to the API section.
* Generate your API key.
* Copy the API key (make sure to save it securely, as it won't be shown again).

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select a Provider">
    On the Integrations page, find the provider you want to set up credentials for. Each provider card shows a brief description and a "Connected" or "Setup Credential" button.

    Click the "Setup Credential" button for Cohere.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select Cohere from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Key: Input the actual API key or credential for Cohere
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Cohere provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Cohere provider credential is now set up and ready to use with the integration system.


# Custom LLM
Source: https://doc.rapida.ai/integrations/llm/custom

Connect Rapida to an OpenAI-compatible or custom LLM endpoint.

Use **Custom LLM** when your model is served from your own endpoint or from a provider that follows an OpenAI-compatible API shape.

## Setup

<Steps>
  <Step title="Create the credential">
    Open **Integrations > Models**, select **Custom LLM**, and create a credential.

    | Field              | Required | Description                                                                                                        |
    | ------------------ | -------: | ------------------------------------------------------------------------------------------------------------------ |
    | `apiCompatibility` |      Yes | Request format. Use `openai_chat_completions`, `openai_compatible`, or `openai_responses` for active chat support. |
    | `baseUrl`          |      Yes | API root for your model server, for example `https://llm.example.com/v1`.                                          |
    | `headers`          |       No | Headers sent with each request, such as `Authorization: Bearer ...`.                                               |
  </Step>

  <Step title="Select the model">
    Open the assistant model settings, select **Custom LLM**, and enter the model ID your server expects.
  </Step>

  <Step title="Configure model parameters">
    Use **Model Parameters** for provider-specific JSON such as temperature, token limits, or extra server options.
  </Step>
</Steps>

## Supported compatibility values

| Value                     | Use for                                                                        |
| ------------------------- | ------------------------------------------------------------------------------ |
| `openai_chat_completions` | Servers compatible with `/v1/chat/completions`.                                |
| `openai_compatible`       | OpenAI-compatible local/model servers such as vLLM, Ollama, LM Studio, or TGI. |
| `openai_responses`        | Servers compatible with `/v1/responses`.                                       |
| `anthropic_messages`      | Credential option only; chat execution is not implemented yet.                 |
| `gemini_generate_content` | Credential option only; chat execution is not implemented yet.                 |

## Example

```json theme={null}
{
  "apiCompatibility": "openai_compatible",
  "baseUrl": "http://localhost:8000/v1",
  "headers": {
    "Authorization": "Bearer local-dev-key"
  }
}
```

```json theme={null}
{
  "model.id": "meta-llama/Llama-3.1-8B-Instruct",
  "model.name": "meta-llama/Llama-3.1-8B-Instruct",
  "model.parameters": {
    "temperature": 0.4,
    "max_tokens": 512,
    "top_p": 0.9
  }
}
```

<Card title="Full Custom LLM reference" icon="network" href="/opensource/services/integration-api/llm/custom">
  Credential fields, model arguments, compatibility notes, and backend mapping.
</Card>


# Gemini / Google AI Studio
Source: https://doc.rapida.ai/integrations/llm/gemini

Gemini is Google's latest family of large language models that can understand and generate text, images, and more.

## Getting Started

To integrate Gemini with your Rapida application, follow these steps:

## Supported Models

Google Gemini offers several advanced language models that can be used with this integration:

| Model Name            | Series     | Description                                                      |
| --------------------- | ---------- | ---------------------------------------------------------------- |
| gemini-2.5-pro        | Gemini 2.5 | Latest Gemini Pro model with advanced reasoning and capabilities |
| gemini-2.5-flash      | Gemini 2.5 | Fast and efficient version of Gemini 2.5                         |
| gemini-2.0-flash      | Gemini 2.0 | Gemini 2.0 Flash model optimized for speed                       |
| gemini-2.0-flash-lite | Gemini 2.0 | Lightweight version of Gemini 2.0 Flash                          |
| gemini-1.5-pro        | Gemini 1.5 | Gemini 1.5 Pro for complex tasks                                 |
| gemini-1.5-flash      | Gemini 1.5 | Gemini 1.5 Flash for fast processing                             |

These models offer various capabilities and performance levels. Choose the appropriate model based on your specific use case and requirements.

## Prerequisites

* Have a Google account with access to Google AI Studio
* Visit [Google AI Studio](https://aistudio.google.com/) to get started
* Generate your API key from the Google AI Studio dashboard
* Copy the API key (make sure to save it securely, as it won't be shown again)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including Gemini, Azure OpenAI, Anthropic, and more.
  </Step>

  <Step title="Select Gemini">
    On the Integrations page, find the Gemini / Google AI Studio provider card.

    Click the "Setup Credential" button for Gemini.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Gemini / Google AI Studio" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Gemini API key from Google AI Studio
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Gemini provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Gemini provider credential is now set up and ready to use with the integration system.

## Integration Features

* **Multimodal Capabilities**: Process text and images
* **Advanced Reasoning**: Powerful reasoning capabilities for complex tasks
* **Fast Processing**: Optimized models for quick response times
* **Free Tier Available**: Get started with Google AI Studio's free tier

For more information, visit the [Google AI Studio](https://aistudio.google.com/).


# Google AI
Source: https://doc.rapida.ai/integrations/llm/google-ai

Google AI provides advanced language models and AI capabilities through a unified API.

## Getting Started

To integrate Google AI with your Rapida application, follow these steps:

## Supported Models

Google AI offers several advanced language models that can be used with this integration. Here's a table of some supported models:

| Model Name                                | Description                                        |
| ----------------------------------------- | -------------------------------------------------- |
| gemini-2.5-pro                            | Latest Gemini Pro model with advanced capabilities |
| gemini-2.5-flash                          | Faster version of Gemini 2.5                       |
| gemini-2.5-flash-lite-preview-06-17       | Preview of lightweight Gemini 2.5 Flash            |
| gemini-2.5-flash-preview-tts              | Gemini 2.5 Flash with text-to-speech preview       |
| gemini-2.5-pro-preview-tts                | Gemini 2.5 Pro with text-to-speech preview         |
| gemini-2.0-flash                          | Gemini 2.0 Flash model                             |
| gemini-2.0-flash-preview-image-generation | Gemini 2.0 Flash with image generation preview     |
| gemini-2.0-flash-lite                     | Lightweight version of Gemini 2.0 Flash            |

Note: Google AI may add or update models over time. Check the Google AI documentation for the most up-to-date list of available models.

## Prerequisites

* Have a Google Cloud account with access to Google AI.
* Set up your Google Cloud project and enable the necessary APIs.
* Ensure you have the required permissions to access Google AI and its models.

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including Google AI, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select Google AI">
    On the Integrations page, find the Google AI provider card.

    Click the "Setup Credential" button for Google AI.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Google AI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Google AI API Key: Input your Google AI API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Google AI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Google AI provider credential is now set up and ready to use with the integration system.


# Google Vertex AI
Source: https://doc.rapida.ai/integrations/llm/google-vertex-ai

Google Vertex AI is a fully-managed, unified AI development platform that provides access to Google's advanced models with enterprise features.

## Getting Started

To integrate Google Vertex AI with your Rapida application, follow these steps:

## Supported Models

Google Vertex AI provides access to multiple advanced models:

| Model Name         | Type      | Description                                        |
| ------------------ | --------- | -------------------------------------------------- |
| gemini-2.5-pro     | Text      | Latest Gemini Pro model with advanced capabilities |
| gemini-2.5-flash   | Text      | Fast Gemini 2.5 model for efficient processing     |
| gemini-2.0-flash   | Text      | Gemini 2.0 Flash for optimized performance         |
| claude-3.5-sonnet  | Text      | Anthropic's Claude 3.5 Sonnet via Vertex AI        |
| llama-2-70b        | Text      | Meta's Llama 2 70B model for open-source users     |
| mistral-large      | Text      | Mistral's large language model                     |
| text-embedding-004 | Embedding | Latest Vertex AI embedding model                   |

Note: Available models may vary by region. Check Vertex AI documentation for the complete list.

## Prerequisites

* Have a Google Cloud account
* Create a new Google Cloud Project or use an existing one
* Enable the Vertex AI API in your Google Cloud Project
* Create a service account with Vertex AI permissions
* Download the service account key (JSON file)
* Set up your Project ID and Region

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including Google Vertex AI, Azure OpenAI, Anthropic, and more.
  </Step>

  <Step title="Select Google Vertex AI">
    On the Integrations page, find the Google Vertex AI provider card.

    Click the "Setup Credential" button for Google Vertex AI.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Google Vertex AI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter Project ID: Input your Google Cloud Project ID
    4. Enter Region: Specify the region where Vertex AI is available (e.g., us-central1)
    5. Enter Service Account Key: Paste the entire JSON content of your service account key
    6. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Google Vertex AI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Google Vertex AI provider credential is now set up and ready to use with the integration system.

## Integration Features

* **Enterprise-Grade**: Full enterprise features and compliance
* **Multi-Model Support**: Access to Google's latest models and third-party models
* **Model Garden**: Fine-tune and deploy custom models
* **Monitoring**: Built-in monitoring and logging for production deployments
* **Scalability**: Automatic scaling for your AI workloads

For more information, visit the [Google Vertex AI documentation](https://cloud.google.com/vertex-ai/docs).


# Hugging Face
Source: https://doc.rapida.ai/integrations/llm/huggingface

Hugging Face provides a wide range of open-source models and AI capabilities through their Inference API.

## Getting Started

To integrate Hugging Face with your Rapida application, follow these steps:

## Supported Models and Capabilities

Hugging Face offers a vast array of open-source models that can be used with this integration. Here's a table of some supported capabilities:

| Provider       | Supported |
| -------------- | --------- |
| Cerebras       | ✅         |
| Cohere         | ✅         |
| Fal AI         | ✅         |
| Featherless AI | ✅         |
| Fireworks      | ✅         |
| Groq           | ✅         |
| HF Inference   | ✅         |
| Hyperbolic     | ✅         |
| Nebius         | ✅         |
| Novita         | ✅         |
| Nscale         | ✅         |
| Replicate      | ✅         |
| SambaNova      | ✅         |
| Together       | ✅         |

Note: Hugging Face's model ecosystem is constantly growing. Check the Hugging Face Hub for the most up-to-date list of available models and their capabilities.

## Prerequisites

* Have a Hugging Face account.
* Generate an API token from your Hugging Face account settings.
* If using custom models, ensure they are deployed to the Hugging Face Inference API.

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including Hugging Face, OpenAI, Google AI, and more.
  </Step>

  <Step title="Select Hugging Face">
    On the Integrations page, find the Hugging Face provider card.

    Click the "Setup Credential" button for Hugging Face.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Hugging Face" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Hugging Face API Token: Input your Hugging Face API token
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    <img alt="View Provider Credential" />

    After setting up the credential, you can verify it's been added:

    1. The Hugging Face provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Hugging Face provider credential is now set up and ready to use with the integration system.

## Using Custom Models with Hugging Face Inference API

To use your custom models deployed on the Hugging Face Inference API:

1. Deploy your model to the Hugging Face Inference API through your Hugging Face account.
2. Note down the model deployment endpoint URL. It typically looks like:
   `https://api-inference.huggingface.co/models/YOUR_USERNAME/YOUR_MODEL_NAME`
3. When configuring your Rapida application to use this model, use the full endpoint URL as the model identifier.


# Mistral
Source: https://doc.rapida.ai/integrations/llm/mistral

Mistral specializes in creating fast, secure, open-source large language models with excellent performance-to-cost ratio.

## Getting Started

To integrate Mistral with your Rapida application, follow these steps:

## Supported Models

Mistral offers several high-performance language models:

| Model Name            | Type   | Description                                    |
| --------------------- | ------ | ---------------------------------------------- |
| mistral-large-latest  | Large  | Most capable model with advanced reasoning     |
| mistral-medium-latest | Medium | Balanced performance and speed                 |
| mistral-small-latest  | Small  | Lightweight model for cost-effective solutions |
| open-mistral-7b       | Open   | Open-source 7B model                           |
| open-mixtral-8x7b     | Open   | Open-source mixture of experts model           |
| open-mixtral-8x22b    | Open   | Large open-source mixture of experts model     |

These models offer various capabilities and performance levels. Choose the appropriate model based on your specific use case and requirements.

## Prerequisites

* Go to the Mistral platform at [https://mistral.ai](https://mistral.ai)
* Sign up or log in to your Mistral account
* Navigate to the API section in your account dashboard
* Generate your API key
* Copy the API key (make sure to save it securely, as it won't be shown again)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including Mistral, Azure OpenAI, Anthropic, and more.
  </Step>

  <Step title="Select Mistral">
    On the Integrations page, find the Mistral provider card.

    Click the "Setup Credential" button for Mistral.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Mistral" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Mistral API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Mistral provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Mistral provider credential is now set up and ready to use with the integration system.

## Integration Features

* **Fast Inference**: Optimized for quick response times
* **Cost-Effective**: Excellent performance-to-cost ratio
* **Open-Source Options**: Access to open-source models
* **Multilingual Support**: Support for multiple languages
* **Fine-tuning**: Ability to fine-tune models for specific tasks

For more information, visit the [Mistral documentation](https://docs.mistral.ai/).


# OpenAI
Source: https://doc.rapida.ai/integrations/llm/openai

OpenAI is a leading AI research and deployment company, known for its advanced language models like GPT-3 and GPT-4.

## Getting Started

To integrate OpenAI with your Rapida application, follow these steps:

# Supported Models

OpenAI offers a variety of models that can be used with this integration. Here's a table of the supported models:

| Model Name             | Series   | Description                                                |
| ---------------------- | -------- | ---------------------------------------------------------- |
| gpt-4                  | GPT-4    | Latest GPT-4 model with improved performance               |
| gpt-4-0613             | GPT-4    | June 2023 version of GPT-4                                 |
| gpt-4o                 | GPT-4    | Optimized version of GPT-4                                 |
| gpt-4-turbo-preview    | GPT-4    | Preview of the turbo version of GPT-4                      |
| gpt-4-turbo            | GPT-4    | Turbo version of GPT-4 for faster processing               |
| gpt-4.1-mini           | GPT-4    | Smaller, faster version of GPT-4.1                         |
| gpt-4.1-nano           | GPT-4    | Nano-sized version of GPT-4.1 for lightweight applications |
| gpt-3.5-turbo          | GPT-3.5  | Optimized version of GPT-3.5 for chat-based applications   |
| gpt-3.5-turbo-16k      | GPT-3.5  | GPT-3.5 turbo with expanded 16k token context              |
| gpt-3.5-turbo-16k-0613 | GPT-3.5  | June 2023 version of GPT-3.5 turbo with 16k token context  |
| o3-mini                | O Series | Mini version of the O3 model                               |
| o3                     | O Series | Standard O3 model                                          |
| o3-pro                 | O Series | Professional version of the O3 model                       |
| o4-mini                | O Series | Mini version of the O4 model                               |
| gpt-4o-mini            | O Series | Mini version of GPT-4 optimized                            |
| o1                     | O Series | Standard O1 model                                          |
| o1-pro                 | O Series | Professional version of the O1 model                       |

These models offer various capabilities and performance levels. Choose the appropriate model based on your specific use case and requirements.

In addition to the language models, OpenAI also provides embedding models. Here's a table of the supported embedding models:

| Model Name             | Description                               |
| ---------------------- | ----------------------------------------- |
| text-embedding-3-large | Large version of the text embedding model |
| text-embedding-3-small | Small version of the text embedding model |
| text-embedding-ada-002 | Ada-based text embedding model            |

These embedding models are designed to convert text into numerical vectors, which can be used for various natural language processing tasks such as semantic search, clustering, and similarity comparisons.

## Prerequisites

* Go to the OpenAI platform at [https://platform.openai.com](https://platform.openai.com).
* Sign up or log in to your OpenAI account.
* Navigate to the API section.
* Click on "Create new secret key" to generate your API key.
* Copy the API key (make sure to save it securely, as it won't be shown again).

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, OpenAI, and more.
  </Step>

  <Step title="Select a Provider">
    On the Integrations page, find the provider you want to set up credentials for. Each provider card shows a brief description and a "Connected" or "Setup Credential" button.

    Click the "Setup Credential" button for your chosen provider.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select Your Provider from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Key: Input the actual API key or credential for the provider
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your provider credential is now set up and ready to use with the integration system.


# VoyageAI
Source: https://doc.rapida.ai/integrations/llm/voyageai

VoyageAI is an AI company that provides advanced language models and AI solutions for various applications.

## Getting Started

To integrate VoyageAI with your Rapida application, follow these steps:

# Supported Models

VoyageAI offers a range of embedding models that can be used with this integration. Here's a table of the supported models:

| Model Name              | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| voyage-2                | General-purpose embedding model                           |
| voyage-code-2           | Specialized embedding model for code-related tasks        |
| voyage-finance-2        | Embedding model optimized for financial applications      |
| voyage-large-2          | Large-scale general-purpose embedding model               |
| voyage-large-2-instruct | Instruction-tuned version of the large embedding model    |
| voyage-law-2            | Embedding model tailored for legal and law-related tasks  |
| voyage-multilingual-2   | Multilingual embedding model supporting various languages |

These embedding models offer various capabilities and are optimized for different domains. Choose the appropriate model based on your specific use case and requirements.

Note: These models are specifically designed for generating embeddings, which are numerical representations of text that capture semantic meaning. They are particularly useful for tasks such as semantic search, clustering, and recommendation systems.

## Prerequisites

* Go to the VoyageAI platform at [https://www.voyageai.com](https://www.voyageai.com).
* Sign up or log in to your VoyageAI account.
* Navigate to the API section.
* Generate your API key.
* Copy the API key (make sure to save it securely, as it won't be shown again).

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various AI model providers including AWS Bedrock, Azure OpenAI, Anthropic, Cohere, VoyageAI, and more.
  </Step>

  <Step title="Select a Provider">
    On the Integrations page, find the VoyageAI provider card. Click the "Setup Credential" button for VoyageAI.
  </Step>

  <Step title="Create Provider Credential">
    <img alt="Create Provider Credential" />

    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select VoyageAI from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the Key: Input the actual API key for VoyageAI
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The VoyageAI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your VoyageAI provider credential is now set up and ready to use with the integration system.


# AssemblyAI
Source: https://doc.rapida.ai/integrations/stt/assemblyai

AssemblyAI provides advanced speech-to-text with AI-powered audio intelligence features.

## Getting Started

To integrate AssemblyAI with your Rapida application for speech-to-text (STT) capabilities, follow these steps:

## Supported Models

### Speech-to-Text Models

| Model Name | Description                    | Best For                          |
| ---------- | ------------------------------ | --------------------------------- |
| best       | AssemblyAI's latest best model | High accuracy, general purpose    |
| nano       | Lightweight model              | Cost-effective, faster processing |

### Languages Supported

AssemblyAI supports automatic language detection and can recognize content in 99+ languages.

Popular supported languages include:

* English (US, UK, Australian, Indian variants)
* Spanish, French, German, Italian
* Mandarin, Cantonese, Japanese, Korean
* Hindi, Portuguese, Russian, Arabic, and many more

## Supported Features

* **Speaker Diarization**: Identify different speakers in conversations
* **Sentiment Analysis**: Analyze sentiment of transcribed content
* **Entity Detection**: Automatically detect entities (names, locations, etc.)
* **Profanity Filtering**: Filter or redact profanity
* **Auto Chapters**: Automatically segment transcripts into chapters
* **Summarization**: Get AI-generated summaries of transcribed content
* **Custom Vocabulary**: Define custom words and terminology

## Prerequisites

* Have an AssemblyAI account (sign up at [https://www.assemblyai.com](https://www.assemblyai.com))
* Navigate to your dashboard
* Go to the API tokens section
* Generate a new API token
* Copy the API token (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access speech service providers.
  </Step>

  <Step title="Select AssemblyAI">
    On the Integrations page, find the AssemblyAI provider card.

    Click the "Setup Credential" button for AssemblyAI.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "AssemblyAI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Token: Input your AssemblyAI API token
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The AssemblyAI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your AssemblyAI provider credential is now set up for speech-to-text integration.

## Integration Features

* **High Accuracy**: Industry-leading transcription accuracy
* **AI-Powered Features**: Built-in sentiment analysis and entity detection
* **99+ Languages**: Supports automatic detection across 99+ languages
* **Real-time & Batch**: Both streaming and batch processing options
* **Speaker Diarization**: Automatically identify different speakers
* **Profanity Detection**: Filter or redact inappropriate language
* **Summarization**: Generate automatic summaries of conversations

For more information, visit the [AssemblyAI documentation](https://www.assemblyai.com/docs).


# AWS Transcribe
Source: https://doc.rapida.ai/integrations/stt/aws-transcribe

Amazon Transcribe is a fully managed automatic speech recognition (ASR) service that makes it easy to add speech-to-text capabilities to applications.

Amazon Transcribe delivers real-time and batch speech recognition with support for custom vocabularies, speaker diarization, and content redaction. It integrates natively with AWS infrastructure for low-latency voice workloads.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add AWS credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard and add your AWS Access Key ID and Secret Access Key. Ensure the associated IAM role has `AmazonTranscribeFullAccess` (or a scoped equivalent).
  </Step>

  <Step title="Select AWS Transcribe as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **AWS** as your Speech-to-Text provider.
  </Step>

  <Step title="Select a region">
    Choose the AWS region closest to your deployment for lowest latency (e.g. `us-east-1`, `eu-west-1`, `ap-southeast-1`).
  </Step>
</Steps>

## Key Features

* **Real-time streaming**: Low-latency streaming transcription for live voice applications
* **Custom vocabularies**: Improve accuracy for domain-specific terms (medical, legal, technical)
* **Speaker diarization**: Identify and separate multiple speakers in a conversation
* **Content redaction**: Automatically redact PII (names, phone numbers, SSNs) from transcripts
* **Custom language models**: Train models on domain-specific text corpora

## Supported Languages

Amazon Transcribe supports 100+ languages and dialects. For streaming transcription, availability varies by region. See the [AWS Transcribe documentation](https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html) for a full list.

## Configuration Options

| Option          | Description                                  |
| --------------- | -------------------------------------------- |
| Region          | AWS region for the Transcribe service        |
| Language code   | BCP-47 language code (e.g. `en-US`, `es-US`) |
| Vocabulary name | Optional custom vocabulary to use            |
| Sample rate     | Audio sample rate in Hz (8000 or 16000)      |

## Notes

* AWS Transcribe streaming uses WebSocket connections; Rapida manages the connection lifecycle.
* For lower cost on non-real-time workloads, batch transcription is available via the REST API.
* Costs are billed per second of audio processed. See [AWS Transcribe pricing](https://aws.amazon.com/transcribe/pricing/).

## Related

* [AWS Polly TTS](/integrations/tts/aws-polly)


# Azure Cognitive Services
Source: https://doc.rapida.ai/integrations/stt/azure-speech-service

Azure Cognitive Services Speech-to-Text provides real-time and batch transcription in 100+ languages.

Azure Cognitive Services Speech provides cloud-based automatic speech recognition (ASR) built on Microsoft's neural network models. It supports real-time streaming transcription, diarization, and custom models — making it a strong choice for enterprise voice applications.

## Getting Started

Follow these steps to configure Azure Cognitive Services as your STT provider:

<Steps>
  <Step title="Add Azure credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Azure Subscription Key and the endpoint URL for your Speech resource. The IAM role must have the `Cognitive Services User` permission.
  </Step>

  <Step title="Select Azure as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **Azure Cognitive Services** as your Speech-to-Text provider.
  </Step>

  <Step title="Choose a language">
    Select the BCP-47 language code for your primary language (e.g. `en-US`, `es-ES`, `fr-FR`). Azure supports 100+ languages and locales.
  </Step>
</Steps>

## Supported Models

| Model    | Description                                                 |
| -------- | ----------------------------------------------------------- |
| `latest` | Microsoft's latest neural ASR model for the selected locale |
| Custom   | Custom Speech models trained on your own audio data         |

## Key Features

* **Real-time streaming**: Low-latency partial and final transcripts for live voice applications
* **Speaker diarization**: Identify and label individual speakers in a conversation
* **Custom Speech models**: Train on your own audio data to improve accuracy for domain-specific terms
* **Profanity filtering**: Mask or remove profane words from transcripts
* **Phrase lists**: Boost recognition accuracy for specific words or phrases
* **Content redaction**: Automatically redact PII from transcripts

## Supported Languages

Azure supports 100+ languages and locales including English (US, UK, AU, IN), Spanish, French, German, Italian, Portuguese, Japanese, Chinese (Simplified, Traditional), Korean, Hindi, and Arabic. See the [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support) for the full list.

## Configuration Options

| Option           | Description                                   |
| ---------------- | --------------------------------------------- |
| Subscription key | Azure Cognitive Services authentication key   |
| Endpoint         | Azure Speech resource endpoint URL            |
| Region           | Azure region (e.g. `eastus`, `westeurope`)    |
| Language code    | BCP-47 locale code                            |
| Sample rate      | Audio input sample rate in Hz (8000 or 16000) |

## Notes

* For telephony use cases, set sample rate to 8000 Hz to match PSTN audio.
* Custom Speech models require training data upload via the Azure portal.
* Pricing is per audio hour. See [Azure Speech pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/speech-services/).

## Related

* [Azure Speech TTS](/integrations/tts/azure-speech-service)
* [Deepgram STT](/integrations/stt/deepgram)
* [AWS Transcribe STT](/integrations/stt/aws-transcribe)


# Cartesia
Source: https://doc.rapida.ai/integrations/stt/cartesia

Cartesia provides advanced voice AI solutions with both speech-to-text and text-to-speech capabilities.

## Getting Started

To integrate Cartesia with your Rapida application for speech-to-text (STT) and text-to-speech (TTS) capabilities, follow these steps:

## Supported Models

### Speech-to-Text Models

| Model Name         | Language     | Description                              |
| ------------------ | ------------ | ---------------------------------------- |
| Sonic English      | English      | High-accuracy English speech recognition |
| Sonic Multilingual | Multilingual | Support for multiple languages           |

### Text-to-Speech Models

| Model Name | Features                    | Best For                             |
| ---------- | --------------------------- | ------------------------------------ |
| Bark       | Expressive speech synthesis | Natural-sounding voices with emotion |
| Tortoise   | High-quality TTS            | Professional voice applications      |
| Sonic XL   | Ultra-realistic voices      | High-fidelity voice synthesis        |

### Supported Languages for STT

* English (US, UK, Australian variants)
* Spanish, French, German
* Mandarin, Japanese, Korean
* And more

### Supported Languages for TTS

Cartesia supports 20+ languages for text-to-speech synthesis with multiple voice options.

## Prerequisites

* Have a Cartesia account (sign up at [https://cartesia.ai](https://cartesia.ai))
* Navigate to your API dashboard
* Generate an API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access voice service providers.
  </Step>

  <Step title="Select Cartesia">
    On the Integrations page, find the Cartesia provider card.

    Click the "Setup Credential" button for Cartesia.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Cartesia" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Cartesia API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Cartesia provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Cartesia provider credential is now set up for voice AI integration.

## Integration Features

* **Unified Platform**: Both STT and TTS in one platform
* **High-Quality Audio**: Professional-grade voice synthesis
* **Real-time Processing**: Low-latency speech processing
* **Multiple Languages**: Comprehensive language support
* **Voice Customization**: Create custom voices and speaking styles
* **Streaming Support**: Real-time streaming for both STT and TTS

For more information, visit the [Cartesia documentation](https://www.cartesia.ai/).


# Custom Speech-to-Text
Source: https://doc.rapida.ai/integrations/stt/custom

Configure a custom WebSocket or HTTP speech-to-text provider with credentials, audio settings, query parameters, request rules, response rules, and the Rapida DSL.

Custom Speech-to-Text lets you connect Rapida to a transcription service that is not available as a built-in STT provider. You provide the provider endpoint, authentication headers, audio format, and a JSON DSL that tells Rapida how to send audio and how to read transcripts from provider responses.

Use Custom STT when your provider can do one of the following:

* Accept streaming audio over WebSocket.
* Accept one HTTP transcription request after the user finishes speaking.

**Provider identifier:** `custom-stt`

**API compatibility:** `websocket_v1` or `http_v1`

<Info>
  Custom STT is configured from credentials and assistant voice input settings. You do not need to write a new Rapida transformer when the provider protocol can be described with the DSL on this page.
</Info>

## Setup flow

<Steps>
  <Step title="Confirm the provider protocol">
    Decide whether your STT provider should be configured as `websocket_v1` or `http_v1`.

    Use `websocket_v1` when the provider opens a persistent WebSocket connection and receives audio chunks while the user is speaking.

    Use `http_v1` when the provider receives one JSON POST per completed speech segment and returns a transcript in the HTTP response.
  </Step>

  <Step title="Create the Custom STT credential">
    Open **Credentials** or **Integrations > Models**, choose **Custom STT**, and create a credential with `apiCompatibility`, `baseUrl`, and any required `headers`.
  </Step>

  <Step title="Select Custom STT for voice input">
    Open the assistant or deployment voice settings, go to **Voice Input**, and select **Custom STT** as the speech-to-text provider.
  </Step>

  <Step title="Set the audio format">
    Choose the audio encoding and sample rate that your provider expects.

    Rapida prepares audio before the request rules run. The DSL can then read the configured values from `config.audio.encoding`, `config.audio.sample_rate`, `encoding`, and `sample_rate`.
  </Step>

  <Step title="Write the DSL configuration">
    Fill `listen.query_params`, `listen.request_rules`, and `listen.response_rules`.

    Query parameters build the provider URL. Request rules map Rapida packets to outbound provider frames or HTTP JSON bodies. Response rules map provider responses to transcripts or errors.
  </Step>

  <Step title="Test with a real call or debugger session">
    Confirm that the provider receives audio, that transcripts appear in conversation logs, and that partial and final transcripts use the correct `interim` value.
  </Step>
</Steps>

## Credential fields

Create one credential for the external STT provider.

| Field              | Required | Description                                                                                                                                                                            |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiCompatibility` | No       | Selects the transport. Use `websocket_v1` for streaming WebSocket STT or `http_v1` for one HTTP request per completed speech segment. Defaults to `websocket_v1` when omitted.         |
| `baseUrl`          | Yes      | Provider endpoint URL. Use a WebSocket URL such as `wss://stt.example.com/v1/listen` for `websocket_v1`, or an HTTP URL such as `https://stt.example.com/v1/transcribe` for `http_v1`. |
| `headers`          | No       | Static header map sent to the provider. Use this for authorization and provider-required headers, for example `{"Authorization":"Bearer sk_..."}`.                                     |

The runtime also accepts snake case credential keys: `api_compatibility` and `base_url`.

<Warning>
  Headers are static credential values. The DSL cannot template headers, read environment variables, sign requests, or change the URL path dynamically.
</Warning>

## Assistant STT arguments

These fields are configured on the assistant or deployment voice input provider. The UI stores them with the provider metadata, and the runtime reads the option keys shown below.

| Option key                 | Required | Default    | Description                                                                                                                                                                                                                                         |
| -------------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listen.audio.encoding`    | Yes      | `LINEAR16` | Audio encoding setting exposed to the DSL as `encoding` and `config.audio.encoding`. For `websocket_v1`, binary audio is prepared with this encoding. Supported values are `LINEAR16` and `MuLaw8`.                                                 |
| `listen.audio.sample_rate` | Yes      | `16000`    | Audio sample rate used while preparing audio and exposed to the DSL as `sample_rate` and `config.audio.sample_rate`. Supported UI values are `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, and `48000`.                                      |
| `listen.query_params`      | No       | `{}`       | Flat JSON object appended to `baseUrl` as query parameters. Values can be static primitives or query DSL expressions.                                                                                                                               |
| `listen.request_rules`     | Yes      | None       | Ordered JSON array that maps Rapida packets to outbound provider messages. Must contain at least one rule with `when.packet` set to `audio`.                                                                                                        |
| `listen.response_rules`    | Yes      | None       | Ordered JSON array that maps provider responses to Rapida transcript or error events. Must contain at least one rule.                                                                                                                               |
| `listen.model`             | No       | Empty      | Optional provider model identifier. When present, query params can read it with `{ "$var": "model" }` and request rules can read it with `{ "$path": "config.model" }`.                                                                             |
| `listen.language`          | No       | Empty      | Optional provider language code. When present, query params can read it with `{ "$var": "language" }` and request rules can read it with `{ "$path": "config.language" }`. Response rules fall back to this value when they do not emit `language`. |

<Note>
  The UI exposes the audio and DSL fields. `listen.model` and `listen.language` are optional metadata keys for API-driven or imported configurations. If your provider needs fixed model or language values and those fields are not available in your UI, put the values directly in query params or request rules.
</Note>

<Info>
  When you work with raw assistant metadata, use the unprefixed custom STT option keys, such as `listen.request_rules`. The UI may preserve other microphone-level settings under `microphone.*`, but the custom STT DSL fields are the `listen.*` keys listed above.
</Info>

## Choose WebSocket or HTTP

| Compatibility  | How Rapida sends audio                                                                                                                                                          | Request rule requirement                                                                        | Response source                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `websocket_v1` | Opens a WebSocket connection and sends matching request rules as provider frames.                                                                                               | At least one `audio` request rule. The outbound frame can be `binary`, `json`, or `text`.       | Each provider WebSocket message is parsed and matched against `listen.response_rules`. |
| `http_v1`      | Buffers audio while the user speaks, then sends one HTTP POST when speech ends. The request scope provides raw PCM bytes, PCM base64, and WAV base64 for the completed segment. | The first matching `audio` rule must use `send.frame: "json"` because Rapida posts a JSON body. | The HTTP response body is parsed and matched against `listen.response_rules`.          |

<Warning>
  For `http_v1`, `turn_change` and `interrupt` request rules do not send provider requests. HTTP STT sends only the buffered `audio` rule after speech ends.
</Warning>

## DSL overview

Custom STT has three DSL sections.

| Section          | Option key              | Purpose                                                                                               |
| ---------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| Query parameters | `listen.query_params`   | Adds provider settings to the URL, such as model, language, encoding, and sample rate.                |
| Request rules    | `listen.request_rules`  | Converts Rapida audio lifecycle packets into provider WebSocket frames or the HTTP JSON request body. |
| Response rules   | `listen.response_rules` | Converts provider WebSocket messages or HTTP response bodies into transcript or error events.         |

The DSL is intentionally small. It does not run JavaScript, call functions, perform regex matching, concatenate strings, perform compound conditions, read environment variables, or compute authentication signatures.

## Query parameters

Use `listen.query_params` when your provider expects configuration in the URL.

```json theme={null}
{
  "language": { "$var": "language" },
  "model": { "$var": "model" },
  "encoding": { "$var": "encoding" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

### Query variable reference

Query parameter expressions can use `$var` to read these variables.

| Variable      | Source value               | Example output |
| ------------- | -------------------------- | -------------- |
| `model`       | `listen.model`             | `nova-3`       |
| `language`    | `listen.language`          | `en-US`        |
| `encoding`    | `listen.audio.encoding`    | `LINEAR16`     |
| `sample_rate` | `listen.audio.sample_rate` | `16000`        |

### Query parameter rules

* `listen.query_params` must be a JSON object.
* The object must be flat. A query parameter value cannot be a nested object or array unless that object is a supported DSL expression.
* Each rendered value must be a primitive supported by the UI validator: string, number, or boolean.
* Existing query parameters in `baseUrl` are preserved unless `listen.query_params` renders the same key.
* A key that starts with `$` is treated as an unsupported operator and is rejected.

This configuration:

```json theme={null}
{
  "diarize": true,
  "language": { "$var": "language" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

can produce a provider URL like:

```text theme={null}
wss://stt.example.com/v1/listen?diarize=true&language=en-US&sample_rate=16000
```

## Request rules

`listen.request_rules` is an ordered JSON array. Each rule has a `when` block and a `send` block.

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  }
]
```

| Field         | Required | Description                                                                                         |
| ------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `when.packet` | Yes      | Rapida packet that triggers the rule. Supported values are `turn_change`, `audio`, and `interrupt`. |
| `send.frame`  | Yes      | Outbound provider message type. Supported values are `binary`, `json`, and `text`.                  |
| `send.body`   | Yes      | Static value or DSL expression tree used as the outbound body.                                      |

### Request packet reference

| Packet        | When Rapida sends it                       | Common use                                                                             |
| ------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
| `turn_change` | A new conversation turn or context starts. | Send a provider session-start or configuration message before audio.                   |
| `audio`       | Audio is ready to send to the provider.    | Send raw audio bytes, base64 audio in JSON, or an HTTP JSON transcription body.        |
| `interrupt`   | User interruption is detected.             | Send a provider flush, cancel, or clear message. Applies to active WebSocket sessions. |

### Request frame reference

| `send.frame` | `send.body` must resolve to | Use when                                                                                   |
| ------------ | --------------------------- | ------------------------------------------------------------------------------------------ |
| `binary`     | Bytes or string             | The provider expects raw audio WebSocket frames.                                           |
| `json`       | Valid JSON value            | The provider expects JSON control messages, JSON audio payloads, or `http_v1` POST bodies. |
| `text`       | Value convertible to string | The provider expects plain text WebSocket messages.                                        |

For `websocket_v1`, every matching rule for a packet is sent in order. This lets one `audio` packet produce more than one provider message when the provider requires it.

For `http_v1`, Rapida evaluates `audio` request rules after speech ends and uses the first matching rule as the HTTP JSON body.

### Request scope

Request rules use `$path` to read from the request scope. The available scope depends on the packet.

For `turn_change`:

```json theme={null}
{
  "config": {
    "model": "nova-3",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "turn_change",
    "context_id": "ctx_123"
  }
}
```

For `audio`:

```json theme={null}
{
  "config": {
    "model": "nova-3",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "audio",
    "context_id": "ctx_123",
    "audio": {
      "bytes": "<raw bytes>",
      "base64": "AAE=",
      "pcm_base64": "AAE=",
      "wav_base64": "UklGRi..."
    }
  }
}
```

For `interrupt`:

```json theme={null}
{
  "config": {
    "model": "nova-3",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "interrupt",
    "context_id": "ctx_123"
  }
}
```

### Request path reference

| Path                       | Available on | Description                                                                                           |
| -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `config.model`             | All packets  | Optional provider model from `listen.model`. Empty when not configured.                               |
| `config.language`          | All packets  | Optional provider language from `listen.language`. Empty when not configured.                         |
| `config.audio.encoding`    | All packets  | Final audio encoding sent to the provider.                                                            |
| `config.audio.sample_rate` | All packets  | Final audio sample rate sent to the provider.                                                         |
| `packet.kind`              | All packets  | Current packet type.                                                                                  |
| `packet.context_id`        | All packets  | Current conversation context ID.                                                                      |
| `packet.audio.bytes`       | `audio` only | Raw audio bytes after audio preparation. Use this for binary WebSocket audio frames.                  |
| `packet.audio.base64`      | `audio` only | Base64-encoded raw audio bytes.                                                                       |
| `packet.audio.pcm_base64`  | `audio` only | Same PCM audio as `packet.audio.base64`. Use when the provider names the field `pcm` or `pcm_base64`. |
| `packet.audio.wav_base64`  | `audio` only | Base64-encoded WAV file containing the PCM audio. Use for HTTP providers that expect a WAV payload.   |

<Warning>
  `packet.audio.*` paths exist only on `audio` packets. A `turn_change` or `interrupt` rule that reads `packet.audio.base64` fails validation or runtime evaluation because those packets do not contain audio.
</Warning>

### Binary audio WebSocket example

Use this when the provider expects raw audio frames.

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  }
]
```

### JSON audio WebSocket example

Use this when the provider expects base64 audio inside JSON.

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "json",
      "body": {
        "type": "audio",
        "audio": { "$path": "packet.audio.base64" },
        "encoding": { "$path": "config.audio.encoding" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  }
]
```

### Start, audio, and interrupt WebSocket example

Use this when the provider expects a start message, binary audio frames, and a flush message on interruption.

```json theme={null}
[
  {
    "when": { "packet": "turn_change" },
    "send": {
      "frame": "json",
      "body": {
        "type": "start",
        "language": { "$path": "config.language" },
        "encoding": { "$path": "config.audio.encoding" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  },
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": { "type": "flush" }
    }
  }
]
```

### HTTP transcription request example

Use this with `apiCompatibility: "http_v1"` when your provider accepts one JSON POST after each completed speech segment.

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "json",
      "body": {
        "audio": { "$path": "packet.audio.wav_base64" },
        "audio_format": "wav",
        "language": { "$path": "config.language" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  }
]
```

<Note>
  For `http_v1`, the first matching `audio` rule must render a `json` frame. `binary` and `text` request frames are valid only for WebSocket STT.
</Note>

## Response rules

`listen.response_rules` is an ordered JSON array. Each provider response is parsed into a `json` or `text` frame, then the first matching response rule is evaluated. Later rules are skipped for that response.

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "final" },
    "emit": {
      "script": { "$path": "text" },
      "interim": false
    }
  }
]
```

| Field         | Required | Description                                                                                                           |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `when.frame`  | Yes      | Provider response frame type. Supported values are `json` and `text`.                                                 |
| `when.path`   | No       | Dot path inside a JSON response frame. Must be paired with `when.equals`. Not allowed for text frames.                |
| `when.equals` | No       | Primitive value compared against `when.path` for JSON frames, or against the full text frame for text frames.         |
| `emit`        | Yes      | Object that tells Rapida what to emit. Supported keys are `script`, `confidence`, `language`, `interim`, and `error`. |

### Response frame parsing

| Provider response                                                          | Parsed as | Notes                                                                                                                               |
| -------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| WebSocket binary message                                                   | `binary`  | Custom STT response rules do not support binary response handling, so binary provider responses are not useful for STT transcripts. |
| WebSocket text message containing one JSON object                          | `json`    | Use `$path` to read fields from the object.                                                                                         |
| WebSocket text message containing a JSON string, number, boolean, or array | `text`    | Non-object JSON values are treated as text for STT response rules.                                                                  |
| WebSocket text message that is not valid JSON                              | `text`    | Use `{ "$frame": "text" }` to read the full text.                                                                                   |
| HTTP response body containing one JSON object                              | `json`    | Used with `http_v1`.                                                                                                                |
| HTTP response body that is not a JSON object                               | `text`    | Used with `http_v1`.                                                                                                                |

### Response matching

| Rule shape                                               | Match behavior                                         |
| -------------------------------------------------------- | ------------------------------------------------------ |
| `{ "frame": "json" }`                                    | Matches any JSON object response.                      |
| `{ "frame": "json", "path": "type", "equals": "final" }` | Matches a JSON object where `type` equals `final`.     |
| `{ "frame": "text" }`                                    | Matches any text response.                             |
| `{ "frame": "text", "equals": "DONE" }`                  | Matches a text response whose full text equals `DONE`. |

For JSON rules, `when.path` and `when.equals` must be provided together. `when.equals` must be a primitive JSON value: string, number, boolean, or null.

For text rules, `when.path` is not allowed. If `when.equals` is omitted, the rule matches any text frame.

### Emit keys

| Emit key     | Required | Type after evaluation | Effect                                                                                                     |
| ------------ | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `script`     | No       | string                | Transcript text. Empty transcripts are ignored.                                                            |
| `confidence` | No       | number                | Transcript confidence. Defaults to `0` when omitted.                                                       |
| `language`   | No       | string                | Transcript language. Falls back to `listen.language` when omitted.                                         |
| `interim`    | No       | boolean               | `true` emits a partial transcript. `false` emits a completed transcript. Defaults to `false` when omitted. |
| `error`      | No       | string                | Emits an STT error instead of a transcript when the value is non-empty.                                    |

<Warning>
  If a response rule emits `error`, Rapida treats the provider response as an STT error. If a rule emits neither a non-empty `script` nor a non-empty `error`, the response is ignored.
</Warning>

### JSON partial and final transcript example

Use this when the provider sends structured response events.

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "partial" },
    "emit": {
      "script": { "$path": "text" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "language": { "$path": "language" },
      "interim": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "final" },
    "emit": {
      "script": { "$path": "text" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "language": { "$path": "language" },
      "interim": false
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "error": { "$path": "error.message" }
    }
  }
]
```

### Nested JSON transcript example

Use numeric path segments to read array indexes.

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "results.0.is_final", "equals": false },
    "emit": {
      "script": { "$path": "results.0.transcript" },
      "interim": true
    }
  },
  {
    "when": { "frame": "json", "path": "results.0.is_final", "equals": true },
    "emit": {
      "script": { "$path": "results.0.transcript" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "results.0.confidence" }
      },
      "interim": false
    }
  }
]
```

### Plain text transcript example

Use this when the provider returns transcript chunks as plain text frames or plain HTTP response text.

```json theme={null}
[
  {
    "when": { "frame": "text" },
    "emit": {
      "script": { "$frame": "text" },
      "interim": false
    }
  }
]
```

## DSL operators

Every DSL operator is a JSON object with one operator key. Operator objects must contain only the operator and its required fields.

### `$var`

Reads a supported query variable inside `listen.query_params`.

```json theme={null}
{ "$var": "language" }
```

| Supported in          | Supported values                               |
| --------------------- | ---------------------------------------------- |
| Query parameters only | `model`, `language`, `encoding`, `sample_rate` |

Rules:

* `$var` must be a non-empty string.
* The operator object must contain only `$var`.
* `$var` is not supported in request rules or response rules. Use `$path` there.

### `$path`

Reads a dot-separated path from the current request scope or JSON response frame.

```json theme={null}
{ "$path": "packet.audio.base64" }
```

```json theme={null}
{ "$path": "results.0.transcript" }
```

| Supported in   | Path source                          |
| -------------- | ------------------------------------ |
| Request rules  | `config` and `packet` request scope. |
| Response rules | Current JSON response object.        |

Rules:

* `$path` must be a non-empty string.
* The operator object must contain only `$path`.
* Dot-separated object keys are traversed by key.
* Arrays are traversed by numeric index, such as `results.0.transcript`.
* Keys that contain a literal dot are not addressable.
* Missing paths in `when.path` cause the rule not to match.
* Missing paths in `send.body` or `emit` cause an error.
* Response rules can use `$path` only when the current frame is `json`.

### `$cast`

Casts a rendered value to another type.

```json theme={null}
{
  "$cast": "number",
  "value": { "$path": "config.audio.sample_rate" }
}
```

| Supported in                                    | Supported casts               |
| ----------------------------------------------- | ----------------------------- |
| Query parameters, request rules, response rules | `string`, `number`, `boolean` |

Rules:

* `$cast` must be `string`, `number`, or `boolean`.
* The operator object must contain only `$cast` and `value`.
* `value` can be a literal or another DSL expression.

Cast behavior:

| Cast      | Behavior                                                                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`  | Converts strings, bytes, numbers, booleans, and null to string form.                                                                                              |
| `number`  | Converts JSON numbers, numeric values, and numeric strings to an integer or float.                                                                                |
| `boolean` | Converts booleans, boolean strings, and numeric values. JSON numbers are accepted as `0` or `1`; typed numeric values use zero as `false` and non-zero as `true`. |

### `$frame`

Reads the full current text response frame.

```json theme={null}
{ "$frame": "text" }
```

| Supported in        | Supported selector |
| ------------------- | ------------------ |
| Response rules only | `text`             |

Rules:

* `$frame` must be `text`.
* The operator object must contain only `$frame`.
* `$frame` is useful when the provider returns the transcript as raw text instead of JSON.
* `$frame: "binary"` and `$frame: "json"` are not supported for Custom STT.

### Unsupported operators and expressions

The following are not supported in Custom STT:

* `$decode`
* `$frame: "binary"`
* `$frame: "json"`
* Regex, contains, starts-with, greater-than, less-than, and compound conditions
* String interpolation or concatenation
* Fallback values inside expressions
* Dynamic headers
* Dynamic URL path segments
* Environment variable reads
* JavaScript or function calls

## Complete WebSocket setup example

Credential:

```json theme={null}
{
  "apiCompatibility": "websocket_v1",
  "baseUrl": "wss://stt.example.com/v1/listen",
  "headers": {
    "Authorization": "Bearer sk_example"
  }
}
```

Audio settings:

```json theme={null}
{
  "listen.audio.encoding": "LINEAR16",
  "listen.audio.sample_rate": "16000"
}
```

Query parameters:

```json theme={null}
{
  "language": "en-US",
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

Request rules:

```json theme={null}
[
  {
    "when": { "packet": "turn_change" },
    "send": {
      "frame": "json",
      "body": {
        "type": "start",
        "encoding": { "$path": "config.audio.encoding" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  },
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  }
]
```

Response rules:

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "event", "equals": "transcript.partial" },
    "emit": {
      "script": { "$path": "transcript" },
      "interim": true
    }
  },
  {
    "when": { "frame": "json", "path": "event", "equals": "transcript.final" },
    "emit": {
      "script": { "$path": "transcript" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "interim": false
    }
  }
]
```

## Complete HTTP setup example

Credential:

```json theme={null}
{
  "apiCompatibility": "http_v1",
  "baseUrl": "https://stt.example.com/v1/transcribe",
  "headers": {
    "Authorization": "Bearer sk_example"
  }
}
```

Audio settings:

```json theme={null}
{
  "listen.audio.encoding": "LINEAR16",
  "listen.audio.sample_rate": "16000"
}
```

Request rules:

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "json",
      "body": {
        "audio": { "$path": "packet.audio.wav_base64" },
        "format": "wav",
        "language": "en-US"
      }
    }
  }
]
```

Response rules for a JSON response like `{ "text": "hello", "confidence": "0.94" }`:

```json theme={null}
[
  {
    "when": { "frame": "json" },
    "emit": {
      "script": { "$path": "text" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "interim": false
    }
  }
]
```

## Runtime behavior

* Rapida builds the final URL from `baseUrl` and `listen.query_params`.
* Rapida sends static `headers` from the credential.
* Rapida prepares audio before evaluating request rules. WebSocket binary audio uses the configured encoding and sample rate; HTTP v1 request scope exposes PCM bytes plus PCM/WAV base64 for the completed speech segment.
* `websocket_v1` opens the WebSocket connection when a `turn_change` or `audio` packet needs to be sent.
* `websocket_v1` sends all matching request rules for each packet.
* `http_v1` buffers user speech audio and sends one HTTP POST when the speech segment ends.
* `http_v1` sets `Content-Type: application/json` when the credential headers do not already include a content type.
* If no response rule matches a provider response, the response is ignored.
* If a response emits non-empty `error`, Rapida emits an STT error.
* If a response emits non-empty `script`, Rapida emits a transcript packet and records the transcript in conversation events.

## Validation checklist

Before saving or testing, confirm the following:

* `apiCompatibility` is `websocket_v1` or `http_v1`.
* `baseUrl` is present and points to the correct provider endpoint.
* `headers` include required provider authentication.
* `listen.audio.encoding` matches the provider expectation.
* `listen.audio.sample_rate` matches the provider expectation.
* `listen.request_rules` is valid JSON and contains at least one `audio` rule.
* `http_v1` uses `send.frame: "json"` for the first matching `audio` rule.
* `listen.response_rules` is valid JSON and contains at least one matching transcript or error rule.
* `interim` is `true` for partial transcripts and `false` for final transcripts.

## Troubleshooting

| Symptom                                               | Likely cause                                                        | What to check                                                                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| WebSocket does not connect                            | Incorrect URL, unsupported compatibility, or authentication failure | Confirm `apiCompatibility`, `baseUrl`, and `headers`.                                                                     |
| HTTP request fails                                    | Endpoint rejects method, headers, body shape, or audio format       | Confirm `baseUrl`, `headers`, and that the `audio` rule emits `send.frame: "json"`.                                       |
| Provider receives no audio                            | Missing or non-matching `audio` request rule                        | Add a rule with `when.packet: "audio"`.                                                                                   |
| Provider expected binary audio but receives JSON      | Wrong request frame                                                 | Use `send.frame: "binary"` with `{ "$path": "packet.audio.bytes" }` for WebSocket binary audio.                           |
| Provider expected JSON but receives binary            | Wrong request frame                                                 | Use `send.frame: "json"` and put audio in `packet.audio.base64`, `packet.audio.pcm_base64`, or `packet.audio.wav_base64`. |
| Transcript never appears                              | Response rules do not match provider responses                      | Check `when.frame`, `when.path`, `when.equals`, and the actual provider response shape.                                   |
| Partial transcripts are stored as final               | Incorrect `interim` value                                           | Emit `interim: true` for partial responses and `interim: false` for final responses.                                      |
| Language is missing                                   | Response did not emit language and `listen.language` is empty       | Emit `language` from the response or configure `listen.language`.                                                         |
| Sample rate is a string but provider expects a number | Missing `$cast`                                                     | Wrap the value with `{ "$cast": "number", "value": ... }`.                                                                |
| A rule works for audio but fails for turn changes     | Rule reads `packet.audio.*` on a non-audio packet                   | Use `packet.audio.*` only inside `audio` rules.                                                                           |

## Related

<CardGroup>
  <Card title="Speech-to-Text" icon="mic" href="/assistants/speech-to-text">
    Configure standard STT providers and transcription tuning.
  </Card>

  <Card title="Listen configuration" icon="audio-lines" href="/assistants/configuration/listen">
    See how STT fits into assistant voice input settings.
  </Card>

  <Card title="Custom TTS" icon="volume-2" href="/integrations/tts/custom">
    Configure a custom text-to-speech provider with the related DSL pattern.
  </Card>

  <Card title="Assistant API Custom STT" icon="code" href="/opensource/services/assistant-api/stt/custom">
    Review runtime behavior for self-hosted assistant-api deployments.
  </Card>
</CardGroup>


# Deepgram
Source: https://doc.rapida.ai/integrations/stt/deepgram

Deepgram provides advanced speech-to-text and text-to-speech capabilities powered by AI.

## Getting Started

To integrate Deepgram with your Rapida application for speech-to-text (STT) capabilities, follow these steps:

## Supported Models

Deepgram offers several models optimized for different scenarios:

### Speech-to-Text Models

| Model Name | Description                              | Best For                       |
| ---------- | ---------------------------------------- | ------------------------------ |
| nova-2     | Latest Deepgram model with high accuracy | General purpose, high accuracy |
| nova       | High accuracy speech recognition         | Most use cases                 |
| enhanced   | Previous generation enhanced model       | Cost-effective option          |
| base       | Basic speech recognition                 | Development and testing        |

### Languages Supported

Deepgram supports 30+ languages including:

* English (US, UK, Australian, Indian variants)
* Spanish, French, German, Italian, Dutch
* Mandarin, Cantonese, Japanese, Korean
* Hindi, Portuguese, Russian, Arabic

### Features

* **Real-time Streaming**: Process audio as it's being spoken
* **Batch Processing**: Transcribe pre-recorded audio
* **Speaker Diarization**: Distinguish between multiple speakers
* **Sentiment Analysis**: Analyze sentiment in speech
* **Intent Recognition**: Identify intent from spoken text

## Prerequisites

* Have a Deepgram account (sign up at [https://deepgram.com](https://deepgram.com))
* Navigate to your account settings
* Go to the API Keys section
* Generate a new API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access the speech service providers.
  </Step>

  <Step title="Select Deepgram">
    On the Integrations page, find the Deepgram provider card.

    Click the "Setup Credential" button for Deepgram.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Deepgram" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Deepgram API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Deepgram provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Deepgram provider credential is now set up for speech-to-text integration.

## Integration Features

* **Ultra-Fast Processing**: Industry-leading transcription speed
* **Multiple Languages**: Support for 30+ languages
* **Real-time and Batch**: Both streaming and batch transcription
* **Speaker Diarization**: Identify different speakers automatically
* **Punctuation**: Automatic punctuation restoration
* **Summaries**: Get summaries of transcribed content
* **Sentiment & Intent**: Advanced audio intelligence features

For more information, visit the [Deepgram documentation](https://developers.deepgram.com/).


# Google Speech Service
Source: https://doc.rapida.ai/integrations/stt/google-speech-service

Google Speech Service provides advanced speech-to-text and text-to-speech capabilities powered by Google Cloud.

## Getting Started

To integrate Google Speech Service with your Rapida application for speech-to-text (STT) capabilities, follow these steps:

## Supported Models

Google Speech Service offers various models optimized for different use cases:

### Speech-to-Text Models

| Model Name  | Description                                | Best For                           |
| ----------- | ------------------------------------------ | ---------------------------------- |
| default     | Google's standard speech recognition model | General purpose speech recognition |
| enhanced    | Enhanced model with better accuracy        | Noisy environments and accents     |
| phone\_call | Optimized for phone call audio             | Telephony applications             |
| video       | Optimized for video audio                  | Video content transcription        |

### Languages Supported

Google Speech Service supports 125+ languages. Some popular ones include:

* English (US, UK, Australia, etc.)
* Spanish, French, German, Italian
* Mandarin, Cantonese, Japanese, Korean
* Hindi, Portuguese, Russian, Arabic

## Prerequisites

* Have a Google Cloud account
* Create a new Google Cloud Project or use an existing one
* Enable the Speech-to-Text API in your Google Cloud Project
* Create a service account with Speech-to-Text permissions
* Download the service account key (JSON file)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page. Here you'll see a grid of various speech service providers.
  </Step>

  <Step title="Select Google Speech Service">
    On the Integrations page, find the Google Speech Service provider card.

    Click the "Setup Credential" button for Google Speech Service.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Google Speech Service" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter Project ID: Input your Google Cloud Project ID
    4. Enter Service Account Key: Paste the entire JSON content of your service account key
    5. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Google Speech Service provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Google Speech Service provider credential is now set up for speech-to-text integration.

## Integration Features

* **High Accuracy**: Industry-leading speech recognition accuracy
* **Multiple Languages**: Support for 125+ languages and variants
* **Real-time Streaming**: Stream audio for real-time transcription
* **Speaker Diarization**: Identify different speakers in audio
* **Word-level Confidence**: Get confidence scores for transcribed words
* **Custom Vocabularies**: Define custom words and phrases

For more information, visit the [Google Cloud Speech-to-Text documentation](https://cloud.google.com/speech-to-text/docs).


# Groq STT
Source: https://doc.rapida.ai/integrations/stt/groq

Groq provides ultra-fast speech-to-text via an OpenAI Whisper-compatible API powered by its LPU inference engine.

## Overview

Groq delivers speech-to-text through its OpenAI Whisper-compatible HTTP API, accelerated by the LPU inference engine for extremely fast transcription. It supports a wide range of languages and is well-suited for real-time voice assistant pipelines that require near-instant transcripts.

## Authentication

| Key   | Description                                               |
| ----- | --------------------------------------------------------- |
| `key` | API key from [console.groq.com](https://console.groq.com) |

## Configuration

| Option     | Description                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| `model`    | Whisper model: `whisper-large-v3-turbo` (fast), `whisper-large-v3` (highest accuracy)                  |
| `language` | ISO-639-1 language code (e.g. `en`, `es`, `fr`, `de`, `ja`, `zh`). Leave blank for automatic detection |

## Getting Started

<Steps>
  <Step title="Add Groq credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Groq API key from your [Groq console](https://console.groq.com).
  </Step>

  <Step title="Select Groq as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **Groq** as your Speech-to-Text provider.
  </Step>

  <Step title="Choose a model and language">
    Select `whisper-large-v3-turbo` for lowest latency or `whisper-large-v3` for maximum accuracy. Optionally set a language code to skip auto-detection.
  </Step>
</Steps>

## Related

* [Groq TTS](/integrations/tts/groq)
* [Deepgram STT](/integrations/stt/deepgram)
* [OpenAI Whisper STT](/integrations/stt/openai-whisper)


# NVIDIA STT
Source: https://doc.rapida.ai/integrations/stt/nvidia

NVIDIA provides enterprise-grade automatic speech recognition via the NVCF API.

## Overview

NVIDIA delivers speech-to-text through the NVIDIA Cloud Functions (NVCF) API, offering enterprise-grade ASR powered by NVIDIA's high-throughput inference infrastructure. It is suitable for enterprise voice deployments requiring scalable, accurate transcription.

## Authentication

| Key           | Description                                               |
| ------------- | --------------------------------------------------------- |
| `key`         | API key from [build.nvidia.com](https://build.nvidia.com) |
| `function_id` | NVCF Function ID for the STT model endpoint               |

## Configuration

| Option     | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| `language` | Language code (e.g. `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`) |

## Getting Started

<Steps>
  <Step title="Add NVIDIA credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your NVIDIA API key and the NVCF Function ID for the desired ASR model from [build.nvidia.com](https://build.nvidia.com).
  </Step>

  <Step title="Select NVIDIA as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **NVIDIA** as your Speech-to-Text provider.
  </Step>

  <Step title="Configure language">
    Set the language code matching your expected input audio. Browse supported languages in the [NVIDIA NIM catalog](https://build.nvidia.com/explore/speech).
  </Step>
</Steps>

## Related

* [NVIDIA TTS](/integrations/tts/nvidia)
* [Azure Speech STT](/integrations/stt/azure-speech-service)


# OpenAI Whisper
Source: https://doc.rapida.ai/integrations/stt/openai-whisper

OpenAI Whisper is a state-of-the-art speech recognition model with broad language support and high accuracy.

OpenAI Whisper is a general-purpose speech recognition model trained on a large, diverse audio dataset. It supports multilingual transcription and translation with strong performance across accents, dialects, and noisy environments.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add OpenAI credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard and add your OpenAI API key. This credential is shared across all OpenAI services (LLM, Whisper STT, and TTS).
  </Step>

  <Step title="Select Whisper as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **OpenAI** as your Speech-to-Text provider.
  </Step>

  <Step title="Choose a model">
    Rapida supports the following Whisper models:

    | Model       | Description                                           |
    | ----------- | ----------------------------------------------------- |
    | `whisper-1` | Standard Whisper model — strong multilingual accuracy |
  </Step>
</Steps>

## Supported Languages

Whisper supports transcription in 99+ languages including English, Spanish, French, German, Japanese, Chinese, Hindi, Arabic, and Portuguese.

## Key Features

* **Noise robustness**: Performs well in challenging acoustic environments
* **Multilingual**: Transcribes 99+ languages without separate language models
* **Punctuation & formatting**: Returns properly punctuated and formatted text
* **Long-form audio**: Handles extended utterances with timestamps

## Configuration Options

| Option      | Description                                                                | Default |
| ----------- | -------------------------------------------------------------------------- | ------- |
| Language    | BCP-47 language code (e.g. `en`, `es`). Leave blank for auto-detection     | Auto    |
| Temperature | Sampling temperature (0–1). Lower values produce more deterministic output | `0`     |
| Prompt      | Optional text to guide transcription style or provide context              | —       |

## Notes

* Whisper is a non-streaming model; Rapida buffers and segments audio before sending to the API.
* For lowest latency in real-time voice, consider Deepgram or AssemblyAI which offer true streaming STT.
* Whisper rate limits and pricing follow your OpenAI account tier.

## Related

* [OpenAI TTS](/integrations/tts/openai-tts)
* [OpenAI LLM](/integrations/llm/openai)


# Rev.ai
Source: https://doc.rapida.ai/integrations/stt/revai

Rev.ai provides highly accurate speech recognition powered by deep learning, with real-time and asynchronous transcription options.

Rev.ai delivers streaming and batch speech recognition with industry-leading accuracy for telephony and media applications. It is particularly well-suited for call center transcription and voice analytics use cases.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add Rev.ai credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Rev.ai Access Token, which you can generate from your [Rev.ai account dashboard](https://www.rev.ai/access_token).
  </Step>

  <Step title="Select Rev.ai as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **Rev.ai** as your Speech-to-Text provider.
  </Step>
</Steps>

## Key Features

* **Streaming transcription**: Real-time partial and final hypotheses for low-latency voice applications
* **High telephony accuracy**: Optimized for 8kHz telephone audio
* **Speaker diarization**: Identify individual speakers in multi-party conversations
* **Custom vocabularies**: Boost recognition of domain-specific terms
* **Confidence scores**: Per-word confidence scores for downstream analytics

## Supported Languages

Rev.ai primarily targets English with specialized models for different English accents and telephony audio. Check the [Rev.ai docs](https://docs.rev.ai) for the current language list.

## Configuration Options

| Option           | Description                                     |
| ---------------- | ----------------------------------------------- |
| Access token     | Rev.ai API access token                         |
| Language         | Language code for transcription (default: `en`) |
| Filter profanity | Enable/disable profanity filtering              |

## Notes

* Rev.ai's streaming API uses a WebSocket-based protocol; Rapida handles the connection automatically.
* Ideal for call center and telephony use cases where audio is 8kHz PCM.

## Related

* [Deepgram STT](/integrations/stt/deepgram)
* [AssemblyAI STT](/integrations/stt/assemblyai)


# Sarvam AI
Source: https://doc.rapida.ai/integrations/stt/sarvam

Sarvam AI provides speech-to-text and text-to-speech solutions with strong support for Indian languages.

## Getting Started

To integrate Sarvam AI with your Rapida application for speech and voice capabilities, follow these steps:

## Supported Models

### Speech-to-Text Models

| Model Name       | Description         | Best For                     |
| ---------------- | ------------------- | ---------------------------- |
| sarvam-speech-en | English STT model   | English speech recognition   |
| sarvam-speech-hi | Hindi STT model     | Hindi speech recognition     |
| sarvam-speech-ml | Malayalam STT model | Malayalam speech recognition |
| sarvam-speech-kn | Kannada STT model   | Kannada speech recognition   |
| sarvam-speech-ta | Tamil STT model     | Tamil speech recognition     |
| sarvam-speech-te | Telugu STT model    | Telugu speech recognition    |

### Text-to-Speech Models

| Model Name    | Language  | Features                           |
| ------------- | --------- | ---------------------------------- |
| sarvam-tts-en | English   | Natural English speech synthesis   |
| sarvam-tts-hi | Hindi     | Natural Hindi speech synthesis     |
| sarvam-tts-ml | Malayalam | Natural Malayalam speech synthesis |
| sarvam-tts-kn | Kannada   | Natural Kannada speech synthesis   |
| sarvam-tts-ta | Tamil     | Natural Tamil speech synthesis     |
| sarvam-tts-te | Telugu    | Natural Telugu speech synthesis    |

## Supported Languages

Sarvam AI specializes in Indian languages and supports:

* **English**: Full support
* **Hindi**: Complete support
* **Regional Languages**: Malayalam, Kannada, Tamil, Telugu, and more

## Prerequisites

* Have a Sarvam AI account (sign up at [https://www.sarvam.ai](https://www.sarvam.ai))
* Navigate to your API dashboard
* Generate an API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access voice service providers.
  </Step>

  <Step title="Select Sarvam AI">
    On the Integrations page, find the Sarvam AI provider card.

    Click the "Setup Credential" button for Sarvam AI.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Sarvam AI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Sarvam AI API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Sarvam AI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Sarvam AI provider credential is now set up for voice AI integration.

## Integration Features

* **Indian Languages**: Best-in-class support for Indian languages
* **Multilingual**: Support for English and major Indian languages
* **High Accuracy**: Optimized models for Indian speech patterns
* **TTS & STT**: Complete voice capabilities
* **Natural Voices**: Natural-sounding speech synthesis
* **Real-time Processing**: Low-latency speech processing
* **Developer Friendly**: Easy-to-use APIs

For more information, visit the [Sarvam AI documentation](https://www.sarvam.ai/).


# Speechmatics
Source: https://doc.rapida.ai/integrations/stt/speechmatics

Speechmatics delivers highly accurate, language-inclusive speech recognition with real-time and batch processing capabilities.

Speechmatics is a speech recognition platform known for its broad language coverage and accuracy across diverse accents and audio conditions. It supports real-time streaming transcription for conversational applications.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add Speechmatics credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Speechmatics API key, available from your [Speechmatics account](https://portal.speechmatics.com).
  </Step>

  <Step title="Select Speechmatics as your STT provider">
    When configuring your assistant, open **Audio Settings** and choose **Speechmatics** as your Speech-to-Text provider.
  </Step>

  <Step title="Choose a language">
    Speechmatics supports 50+ languages. Select the appropriate language code for your use case.
  </Step>
</Steps>

## Key Features

* **Broad language support**: 50+ languages with strong performance in non-English languages
* **Real-time streaming**: Low-latency partial and final transcripts via WebSocket
* **Speaker diarization**: Multi-speaker labelling for call analytics
* **Custom dictionary**: Add domain-specific terminology to improve recognition accuracy
* **Accent robustness**: Trained on diverse speaker populations for improved coverage

## Supported Languages

50+ languages including English, Spanish, French, German, Italian, Portuguese, Japanese, Chinese, Arabic, Dutch, and many more. See [Speechmatics language support](https://docs.speechmatics.com/introduction/supported-languages).

## Configuration Options

| Option          | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| API key         | Speechmatics API authentication key                             |
| Language        | Language code (e.g. `en`, `es`, `fr`)                           |
| Operating point | `standard` or `enhanced` accuracy (enhanced has higher latency) |
| Enable entities | Extract named entities from transcripts                         |

## Notes

* Speechmatics streams over WebSockets; Rapida manages the session lifecycle and reconnection.
* The `enhanced` operating point provides higher accuracy at the cost of additional latency.

## Related

* [Deepgram STT](/integrations/stt/deepgram)
* [Google Speech STT](/integrations/stt/google-speech-service)


# Asterisk
Source: https://doc.rapida.ai/integrations/telephony/asterisk

Connect your Asterisk PBX to Rapida AI for real-time voice conversations using AudioSocket (native TCP) or WebSocket transport

Asterisk is the world's most popular open-source telephony platform. Rapida integrates with Asterisk using two transport methods — **AudioSocket** (native TCP protocol) and **WebSocket** (`chan_websocket`) — enabling real-time bidirectional audio streaming for AI-powered voice conversations.

<Info>
  Both transports follow the same two-phase flow: an HTTP webhook registers the call, then a media connection (TCP or WebSocket) carries the audio. Choose the transport that fits your Asterisk version and network topology.
</Info>

## Transport Comparison

| Feature              | AudioSocket (Native)   | WebSocket                |
| -------------------- | ---------------------- | ------------------------ |
| **Asterisk Module**  | `res_audiosocket`      | `chan_websocket`         |
| **Protocol**         | Raw TCP                | WebSocket (wss\://)      |
| **Port**             | 4573                   | 443 (standard HTTPS)     |
| **Audio Codec**      | SLIN 16-bit 8kHz       | μ-law 8kHz               |
| **Firewall**         | Requires TCP 4573 open | Uses standard HTTPS port |
| **TLS**              | Not built-in           | Native TLS via wss\://   |
| **Asterisk Version** | 16+                    | 20+                      |
| **Best For**         | LAN / private network  | Cloud / NAT traversal    |

***

## Architecture Overview

Both transports share the same backend pipeline. The only difference is the **Streamer layer** that bridges the media connection to the AI pipeline.

```mermaid theme={null}
graph TB
    subgraph Asterisk["Asterisk PBX"]
        DP[Dialplan]
        AS_MOD["res_audiosocket"]
        WS_MOD["chan_websocket"]
    end

    subgraph Rapida["Rapida Voice AI Platform"]
        API["Webhook API<br/>POST /v1/talk/asterisk/call/:assistantId"]

        subgraph Transport["Transport Layer"]
            AS_SRV["AudioSocket Server<br/>TCP :4573"]
            WS_SRV["WebSocket Handler<br/>GET /v1/talk/asterisk/ctx/:contextId"]
        end

        REDIS["Redis<br/>Call Context Store"]

        subgraph Pipeline["AI Pipeline"]
            STT["Speech-to-Text"]
            LLM["LLM Engine"]
            TTS["Text-to-Speech"]
            TOOLS["Tool Execution"]
        end
    end

    DP -->|"1. HTTP GET"| API
    API -->|"Save context"| REDIS
    API -->|"Return contextId"| DP

    DP -->|"2a. TCP connect<br/>(contextId as UUID)"| AS_SRV
    DP -->|"2b. WSS connect<br/>(contextId in URL)"| WS_SRV

    AS_SRV -->|"Resolve"| REDIS
    WS_SRV -->|"Resolve"| REDIS

    AS_SRV <--> STT
    WS_SRV <--> STT
    STT --> LLM
    LLM --> TTS
    LLM --> TOOLS
    TTS --> AS_SRV
    TTS --> WS_SRV
```

### Two-Phase Call Setup

Every Asterisk call (inbound or outbound, AudioSocket or WebSocket) follows this pattern:

1. **Phase 1 — Webhook**: An HTTP request registers the call and gets a `contextId`
2. **Phase 2 — Media**: A transport connection (TCP or WebSocket) streams audio using that `contextId`

This design decouples call setup from media transport, allowing the same webhook to serve both AudioSocket and WebSocket.

***

## Prerequisites

<CardGroup>
  <Card title="Asterisk Server" icon="server">
    Asterisk 16+ (AudioSocket) or 20+ (WebSocket) with the required module loaded
  </Card>

  <Card title="Rapida Account" icon="key">
    Active Rapida account with an API key (`rpd-xxx`)
  </Card>

  <Card title="Voice Assistant" icon="bot">
    A configured Rapida voice assistant with phone deployment enabled
  </Card>

  <Card title="Network Access" icon="network">
    TCP 4573 (AudioSocket) or HTTPS 443 (WebSocket) to Rapida
  </Card>
</CardGroup>

<Note>
  For **outbound calls**, you also need Asterisk ARI enabled with credentials stored in a Rapida vault credential.
</Note>

***

## Quick Start — Inbound Calls

Choose your transport and follow the matching setup:

<Tabs>
  <Tab title="AudioSocket (Native TCP)">
    ### 1. Verify Module

    ```bash theme={null}
    asterisk -rx "module show like audiosocket"
    ```

    If not loaded:

    ```ini theme={null}
    # /etc/asterisk/modules.conf
    [modules]
    load = res_audiosocket.so
    ```

    ### 2. Configure Dialplan

    ```ini theme={null}
    # /etc/asterisk/extensions.conf

    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = websocket-01.in.rapida.ai
    RAPIDA_AS_HOST = socket-01.in.rapida.ai
    RAPIDA_PORT    = 4573
    ASSISTANT_ID   = 123456789

    [rapida-inbound]
    exten => _X.,1,Answer()
     same => n,Set(CHANNEL(audioreadformat)=slin)
     same => n,Set(CHANNEL(audiowriteformat)=slin)
     ; Phase 1: Call the webhook to get contextId
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     ; Phase 2: Connect AudioSocket with contextId as UUID
     same => n,AudioSocket(${CTX},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()
    ```

    ### 3. Reload

    ```bash theme={null}
    asterisk -rx "dialplan reload"
    ```
  </Tab>

  <Tab title="WebSocket">
    ### 1. Verify Module

    ```bash theme={null}
    asterisk -rx "module show like chan_websocket"
    ```

    If not loaded:

    ```ini theme={null}
    # /etc/asterisk/modules.conf
    [modules]
    load = chan_websocket.so
    ```

    ### 2. Configure Dialplan

    ```ini theme={null}
    # /etc/asterisk/extensions.conf

    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = websocket-01.in.rapida.ai
    ASSISTANT_ID   = 123456789

    [rapida-inbound-ws]
    exten => _X.,1,Answer()
     ; Phase 1: Call the webhook to get contextId
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     ; Phase 2: Connect WebSocket with contextId in URL path
     same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${CTX}?x-api-key=${RAPIDA_API_KEY})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()
    ```

    ### 3. Reload

    ```bash theme={null}
    asterisk -rx "dialplan reload"
    ```
  </Tab>
</Tabs>

***

## Inbound Call Flow — Detailed

### Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant Asterisk
    participant API as Rapida Webhook API
    participant Redis
    participant Transport as AudioSocket / WebSocket
    participant AI as AI Pipeline (STT → LLM → TTS)

    Caller->>Asterisk: Dials phone number
    Asterisk->>Asterisk: Answer() + set audio format

    rect rgb(230, 245, 255)
    Note over Asterisk,Redis: Phase 1 — Call Registration
    Asterisk->>API: GET /v1/talk/asterisk/call/{assistantId}?from=+1234
    API->>API: Create conversation
    API->>Redis: Save CallContext (5 min TTL)
    API-->>Asterisk: contextId (plain text)
    end

    rect rgb(230, 255, 230)
    Note over Asterisk,AI: Phase 2 — Media Streaming
    alt AudioSocket
        Asterisk->>Transport: TCP connect → send UUID frame (contextId)
    else WebSocket
        Asterisk->>Transport: WSS connect to /v1/talk/asterisk/ctx/{contextId}
    end
    Transport->>Redis: Resolve + delete CallContext (atomic)
    Transport->>Transport: Create streamer, start AI pipeline

    loop Conversation
        Caller->>Asterisk: Voice audio
        Asterisk->>Transport: Audio frames
        Transport->>AI: Resampled audio → STT
        AI->>AI: LLM generates response
        AI->>Transport: TTS audio
        Transport->>Asterisk: Audio frames
        Asterisk->>Caller: AI speaks
    end
    end

    Caller->>Asterisk: Hangup
    Asterisk->>Transport: Hangup signal
    Transport->>AI: Cleanup
```

### What Happens at Each Step

| Step | Component           | Action                                                                          |
| ---- | ------------------- | ------------------------------------------------------------------------------- |
| 1    | Asterisk dialplan   | Answers call, sets SLIN audio format                                            |
| 2    | `CURL()` function   | HTTP GET to Rapida webhook — creates conversation, saves `CallContext` to Redis |
| 3    | Webhook response    | Returns `contextId` as plain text (UUID)                                        |
| 4a   | `AudioSocket()` app | Opens TCP to Rapida:4573, sends `contextId` as UUID frame                       |
| 4b   | `WebSocket()` app   | Opens WSS to `wss://host/v1/talk/asterisk/ctx/{contextId}`                      |
| 5    | Rapida transport    | Atomically reads and deletes `CallContext` from Redis (prevents replay)         |
| 6    | AI pipeline         | STT → LLM → TTS loop until hangup                                               |

***

## Outbound Call Flow — Detailed

Outbound calls are initiated via the **Rapida SDK** (gRPC `CreatePhoneCall` RPC) or REST API. Rapida uses Asterisk's **ARI (Asterisk REST Interface)** to originate the call.

### Prerequisites for Outbound

<Steps>
  <Step title="Enable ARI on Asterisk">
    ```ini theme={null}
    # /etc/asterisk/ari.conf
    [general]
    enabled = yes
    pretty = yes

    [rapida]
    type = user
    read_only = no
    password = your-ari-password
    ```

    ```ini theme={null}
    # /etc/asterisk/http.conf
    [general]
    enabled = yes
    bindaddr = 0.0.0.0
    bindport = 8088
    ```

    Reload:

    ```bash theme={null}
    asterisk -rx "module reload res_ari.so"
    asterisk -rx "module reload res_http_websocket.so"
    ```
  </Step>

  <Step title="Create Vault Credential in Rapida">
    In the Rapida dashboard, go to **Credentials → Create Credential** and select **Asterisk**. Provide:

    | Field                 | Required | Example                      | Description                     |
    | --------------------- | -------- | ---------------------------- | ------------------------------- |
    | `ari_url`             | Yes      | `http://asterisk.local:8088` | Base URL of Asterisk ARI        |
    | `ari_user`            | Yes      | `rapida`                     | ARI username                    |
    | `ari_password`        | Yes      | `your-ari-password`          | ARI password                    |
    | `endpoint_technology` | No       | `PJSIP`                      | SIP technology (default: PJSIP) |
    | `trunk`               | No       | `my-sip-trunk`               | SIP trunk name for routing      |
  </Step>

  <Step title="Configure Outbound Dialplan">
    ARI can originate calls in two modes. Choose one:

    <Tabs>
      <Tab title="Stasis App Mode (Recommended)">
        ARI originates the channel directly into a Stasis application — no dialplan needed for the outbound leg. The channel is handled programmatically.

        ```ini theme={null}
        # /etc/asterisk/stasis.conf (or use existing ARI app)
        ; No dialplan needed — ARI handles the channel via the "rapida" app
        ```

        Rapida sends: `POST /ari/channels?endpoint=PJSIP/+15551234567&app=rapida`
      </Tab>

      <Tab title="Dialplan Mode">
        ARI originates the channel into a dialplan context, which routes to AudioSocket or WebSocket:

        ```ini theme={null}
        # /etc/asterisk/extensions.conf

        [rapida-outbound]
        exten => s,1,Set(CHANNEL(audioreadformat)=slin)
         same => n,Set(CHANNEL(audiowriteformat)=slin)
         ; RAPIDA_CONTEXT_ID is passed as a channel variable by ARI
         same => n,AudioSocket(${RAPIDA_CONTEXT_ID},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
         same => n,Hangup()

        [rapida-outbound-ws]
        exten => s,1,NoOp(Outbound WebSocket call)
         ; RAPIDA_CONTEXT_ID is passed as a channel variable by ARI
         same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${RAPIDA_CONTEXT_ID}?x-api-key=${RAPIDA_API_KEY})
         same => n,Hangup()
        ```

        Set deployment options in Rapida to route via dialplan:

        * `context`: `rapida-outbound` (or `rapida-outbound-ws`)
        * `extension`: `s`
      </Tab>
    </Tabs>
  </Step>

  <Step title="Assign Credential to Phone Deployment">
    In the assistant's **Phone Deployment**, select the Asterisk vault credential and configure:

    | Option             | Value                   | Description                         |
    | ------------------ | ----------------------- | ----------------------------------- |
    | Telephony Provider | `asterisk`              | Selects Asterisk integration        |
    | Credential         | (your vault credential) | ARI connection details              |
    | Phone Number       | `+15559876543`          | Caller ID for outbound              |
    | Context            | *(optional)*            | Dialplan context for outbound       |
    | Extension          | *(optional)*            | Dialplan extension (default: `s`)   |
    | App                | *(optional)*            | Stasis app name (default: `rapida`) |
  </Step>
</Steps>

### Outbound Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant SDK as Your App / SDK
    participant GRPC as Rapida gRPC API
    participant Redis
    participant ARI as Asterisk ARI
    participant Asterisk
    participant Customer
    participant Transport as AudioSocket / WebSocket

    SDK->>GRPC: CreatePhoneCall(assistantId, toNumber)
    GRPC->>GRPC: Create conversation
    GRPC->>Redis: Save CallContext
    GRPC->>GRPC: Resolve vault credential (ARI creds)

    rect rgb(255, 245, 230)
    Note over GRPC,Asterisk: ARI Origination
    GRPC->>ARI: POST /ari/channels<br/>endpoint=PJSIP/+1555...<br/>variables={"RAPIDA_CONTEXT_ID": "ctx-uuid"}
    ARI->>Asterisk: Create channel
    Asterisk->>Customer: Ring
    Customer-->>Asterisk: Answer
    end

    rect rgb(230, 255, 230)
    Note over Asterisk,Transport: Media Connection
    alt Stasis Mode
        ARI->>Transport: Channel enters Stasis app
    else Dialplan Mode
        Asterisk->>Asterisk: Enter dialplan context
        Asterisk->>Transport: AudioSocket or WebSocket connect
    end

    Transport->>Redis: Resolve + delete CallContext
    Transport->>Transport: Start AI pipeline
    end

    GRPC-->>SDK: { conversationId, status: queued }

    loop Conversation
        Customer->>Transport: Voice
        Transport->>Transport: STT → LLM → TTS
        Transport->>Customer: AI speaks
    end
```

### SDK Code Examples (Outbound)

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from rapida import Rapida

    client = Rapida(api_key="rpd-xxx-your-key")

    call = client.calls.create(
        assistant_id=123456789,
        to_number="+15551234567",
        from_number="+15559876543",  # optional, uses deployment default
        metadata={"campaign": "follow-up"},
    )

    print(f"Call queued: conversation_id={call.conversation.id}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { Rapida } from 'rapida';

    const client = new Rapida({ apiKey: 'rpd-xxx-your-key' });

    const call = await client.calls.create({
      assistantId: 123456789,
      toNumber: '+15551234567',
      fromNumber: '+15559876543',
      metadata: { campaign: 'follow-up' },
    });

    console.log(`Call queued: ${call.conversation.id}`);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import "github.com/rapidaai/rapida"

    client := rapida.NewClient("rpd-xxx-your-key")

    call, err := client.Calls.Create(ctx, &rapida.CreateCallRequest{
        AssistantID: 123456789,
        ToNumber:    "+15551234567",
        FromNumber:  "+15559876543",
        Metadata:    map[string]any{"campaign": "follow-up"},
    })
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.rapida.ai/v1/talk/call \
      -H "Authorization: Bearer rpd-xxx-your-key" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+15551234567",
        "from_number": "+15559876543",
        "metadata": { "campaign": "follow-up" }
      }'
    ```
  </Tab>
</Tabs>

***

## AudioSocket Protocol Reference

### Frame Format

Each frame has a 3-byte header followed by a variable-length payload:

```
+----------+------------------+----------------------+
| Type     | Length            | Payload              |
| 1 byte   | 2 bytes (BE)     | 0-65535 bytes        |
+----------+------------------+----------------------+
```

### Frame Types

| Type    | Hex    | Direction         | Description                      |
| ------- | ------ | ----------------- | -------------------------------- |
| Hangup  | `0x00` | Both              | Call termination                 |
| UUID    | `0x01` | Asterisk → Rapida | Context ID (sent as first frame) |
| Silence | `0x02` | Asterisk → Rapida | Silence indicator                |
| Audio   | `0x10` | Both              | Audio data (SLIN 16-bit)         |
| Error   | `0xFF` | Both              | Error condition                  |

### Audio Format

| Property    | AudioSocket (SLIN)   | WebSocket (μ-law) | Rapida Internal   |
| ----------- | -------------------- | ----------------- | ----------------- |
| Encoding    | Signed Linear 16-bit | μ-law 8-bit       | Linear PCM 16-bit |
| Sample Rate | 8000 Hz              | 8000 Hz           | 16000 Hz          |
| Channels    | Mono                 | Mono              | Mono              |

Rapida handles all resampling and codec conversion transparently.

***

## Status Callbacks

Rapida sends status updates to Asterisk via ARI events. You can also configure a **webhook** on the assistant to receive call lifecycle events.

### Event Callback URL

```
POST https://{RAPIDA_HOST}/v1/talk/asterisk/ctx/{contextId}/event?x-api-key={apiKey}
```

This endpoint is automatically configured during outbound call setup. For inbound calls, Asterisk can optionally POST events to this URL.

### Event Types

| Event             | Trigger                        |
| ----------------- | ------------------------------ |
| `webhook`         | Initial call registration      |
| `channel_created` | ARI channel created (outbound) |
| `call.connected`  | Media connection established   |
| `call.ended`      | Call terminated normally       |
| `call.failed`     | Error during call              |

***

## Credential Configuration

### Vault Credential Fields

When creating an Asterisk credential in the Rapida vault, provide:

```json theme={null}
{
  "ari_url": "http://your-asterisk-server:8088",
  "ari_user": "rapida",
  "ari_password": "your-ari-password",
  "endpoint_technology": "PJSIP",
  "trunk": "my-sip-trunk"
}
```

| Field                 | Required                | Default | Description                                         |
| --------------------- | ----------------------- | ------- | --------------------------------------------------- |
| `ari_url`             | **Yes** (outbound only) | —       | Base URL of Asterisk ARI HTTP server                |
| `ari_user`            | **Yes** (outbound only) | —       | ARI username                                        |
| `ari_password`        | **Yes** (outbound only) | —       | ARI password                                        |
| `endpoint_technology` | No                      | `PJSIP` | Channel technology: `PJSIP`, `SIP`, `IAX2`, `DAHDI` |
| `trunk`               | No                      | —       | SIP trunk for routing: builds `PJSIP/trunk/number`  |

<Warning>
  Vault credentials are encrypted at rest. The ARI password is never exposed in API responses or logs.
</Warning>

### Phone Deployment Options

These options are configured on the assistant's phone deployment:

| Option                | Default  | Description                            |
| --------------------- | -------- | -------------------------------------- |
| `phone`               | —        | Default caller ID for outbound calls   |
| `context`             | *(none)* | Asterisk dialplan context for outbound |
| `extension`           | `s`      | Dialplan extension                     |
| `app`                 | `rapida` | Stasis application name                |
| `endpoint_technology` | `PJSIP`  | Overrides vault credential             |
| `trunk`               | —        | Overrides vault credential             |

***

## Full Configuration Examples

### Example 1: Inbound Only (AudioSocket)

Simplest setup — no ARI needed, no vault credential required for inbound-only.

<Tabs>
  <Tab title="Asterisk Config">
    ```ini theme={null}
    # /etc/asterisk/extensions.conf
    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = websocket-01.in.rapida.ai
    RAPIDA_PORT    = 4573
    ASSISTANT_ID   = 123456789

    [from-pstn]
    ; Route all inbound calls to Rapida AI
    exten => _X.,1,Answer()
     same => n,Set(CHANNEL(audioreadformat)=slin)
     same => n,Set(CHANNEL(audiowriteformat)=slin)
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     same => n,AudioSocket(${CTX},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()
    ```
  </Tab>

  <Tab title="Network Requirements">
    ```
    Asterisk → Rapida: TCP 4573 (AudioSocket)
    Asterisk → Rapida: HTTPS 443 (webhook API)
    ```
  </Tab>
</Tabs>

### Example 2: Inbound Only (WebSocket)

No firewall port needed beyond HTTPS — ideal for cloud-hosted Asterisk.

```ini theme={null}
# /etc/asterisk/extensions.conf
[globals]
RAPIDA_API_KEY = rpd-xxx-your-api-key
RAPIDA_HOST    = websocket-01.in.rapida.ai
ASSISTANT_ID   = 123456789

[from-pstn-ws]
exten => _X.,1,Answer()
 same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
 same => n,GotoIf($["${CTX}" = ""]?error)
 same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${CTX}?x-api-key=${RAPIDA_API_KEY})
 same => n,Hangup()
 same => n(error),Playback(an-error-has-occurred)
 same => n,Hangup()
```

### Example 3: Inbound + Outbound (Full Setup)

Complete setup with ARI for outbound calls and AudioSocket for media.

<Tabs>
  <Tab title="extensions.conf">
    ```ini theme={null}
    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = websocket-01.in.rapida.ai
    RAPIDA_PORT    = 4573
    ASSISTANT_ID   = 123456789

    ; ---- Inbound: PSTN → Rapida AI ----
    [rapida-inbound]
    exten => _X.,1,Answer()
     same => n,Set(CHANNEL(audioreadformat)=slin)
     same => n,Set(CHANNEL(audiowriteformat)=slin)
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     same => n,AudioSocket(${CTX},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()

    ; ---- Outbound: Rapida ARI → Customer ----
    ; ARI originates into this context; RAPIDA_CONTEXT_ID is a channel variable
    [rapida-outbound]
    exten => s,1,Set(CHANNEL(audioreadformat)=slin)
     same => n,Set(CHANNEL(audiowriteformat)=slin)
     same => n,AudioSocket(${RAPIDA_CONTEXT_ID},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
     same => n,Hangup()
    ```
  </Tab>

  <Tab title="ari.conf">
    ```ini theme={null}
    [general]
    enabled = yes
    pretty = yes

    [rapida]
    type = user
    read_only = no
    password = your-ari-password
    ```
  </Tab>

  <Tab title="http.conf">
    ```ini theme={null}
    [general]
    enabled = yes
    bindaddr = 0.0.0.0
    bindport = 8088
    ```
  </Tab>

  <Tab title="Rapida Vault Credential">
    ```json theme={null}
    {
      "ari_url": "http://asterisk.local:8088",
      "ari_user": "rapida",
      "ari_password": "your-ari-password",
      "endpoint_technology": "PJSIP",
      "trunk": "my-sip-trunk"
    }
    ```
  </Tab>

  <Tab title="Deployment Options">
    ```json theme={null}
    {
      "phone": "+15559876543",
      "context": "rapida-outbound",
      "extension": "s"
    }
    ```
  </Tab>

  <Tab title="Network Requirements">
    ```
    Asterisk → Rapida: TCP 4573 (AudioSocket)
    Asterisk → Rapida: HTTPS 443 (webhook API)
    Rapida → Asterisk: TCP 8088 (ARI, outbound only)
    ```
  </Tab>
</Tabs>

### Example 4: WebSocket-Only (Inbound + Outbound)

Zero custom ports — everything runs over HTTPS.

<Tabs>
  <Tab title="extensions.conf">
    ```ini theme={null}
    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = websocket-01.in.rapida.ai
    ASSISTANT_ID   = 123456789

    ; ---- Inbound ----
    [rapida-inbound-ws]
    exten => _X.,1,Answer()
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${CTX}?x-api-key=${RAPIDA_API_KEY})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()

    ; ---- Outbound (ARI routes here with RAPIDA_CONTEXT_ID) ----
    [rapida-outbound-ws]
    exten => s,1,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${RAPIDA_CONTEXT_ID}?x-api-key=${RAPIDA_API_KEY})
     same => n,Hangup()
    ```
  </Tab>

  <Tab title="Rapida Deployment Options">
    ```json theme={null}
    {
      "phone": "+15559876543",
      "context": "rapida-outbound-ws",
      "extension": "s"
    }
    ```
  </Tab>
</Tabs>

***

## Call Lifecycle

### State Machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> Queued: SDK CreatePhoneCall (outbound)
    [*] --> Webhook: Inbound call arrives

    Webhook --> ContextSaved: CallContext saved to Redis
    Queued --> ContextSaved: CallContext saved to Redis

    ContextSaved --> Connected: Transport connects (AudioSocket TCP or WebSocket)
    ContextSaved --> Expired: No connection within 5 min

    Connected --> Active: AI pipeline started
    Active --> Active: Conversation loop

    Active --> Ended: Normal hangup
    Active --> Failed: Error
    Connected --> Failed: Auth error

    Ended --> [*]
    Failed --> [*]
    Expired --> [*]
```

### Captured Metrics

Each call automatically records:

| Metric                 | Description                        |
| ---------------------- | ---------------------------------- |
| `call.duration`        | Total call time (seconds)          |
| `call.talk_duration`   | Active speech time                 |
| `call.status`          | `completed`, `failed`, `no_answer` |
| `call.disconnected_by` | `user`, `assistant`, `system`      |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused (AudioSocket)">
    **Symptoms:** `AudioSocket()` returns immediately, no audio

    **Checklist:**

    * Verify Rapida host is reachable: `nc -zv socket-01.in.rapida.ai 4573`
    * Check firewall allows TCP 4573 outbound
    * Ensure `res_audiosocket.so` is loaded
    * Verify the contextId (token) is non-empty in the dialplan
  </Accordion>

  <Accordion title="WebSocket Connection Failed">
    **Symptoms:** `WebSocket()` fails, no audio

    **Checklist:**

    * Verify WSS URL is correct: `wss://websocket-01.in.rapida.ai/v1/talk/asterisk/ctx/{contextId}?x-api-key={your-api-key}`
    * Ensure `chan_websocket.so` is loaded
    * Check TLS certificate trust on the Asterisk server
    * Verify Asterisk version is 20+ for `chan_websocket`
  </Accordion>

  <Accordion title="Call Context Not Found">
    **Symptoms:** Transport connects but immediately drops with "call context not found"

    **Checklist:**

    * Context ID expires after **5 minutes** — ensure fast connection after webhook
    * Each contextId is single-use (atomically deleted on first connection)
    * Don't reuse contextIds across calls
    * Verify the webhook returned a valid contextId (not an error message)
  </Accordion>

  <Accordion title="No Audio / One-Way Audio (AudioSocket)">
    **Symptoms:** AI speaks but doesn't hear, or vice versa

    **Checklist:**

    * Set `CHANNEL(audioreadformat)=slin` and `CHANNEL(audiowriteformat)=slin`
    * Verify `res_audiosocket` module is loaded
    * Check Asterisk timing: `asterisk -rx "timing test"`
  </Accordion>

  <Accordion title="Choppy Audio / Delays">
    **Symptoms:** Audio artifacts, long pauses

    **Checklist:**

    * Check network latency to Rapida: `ping websocket-01.in.rapida.ai` (target \< 100ms)
    * Verify no packet loss on the path
    * For WebSocket: ensure no proxy is buffering WebSocket frames
    * Reduce network hops if possible
  </Accordion>

  <Accordion title="ARI Outbound Call Fails">
    **Symptoms:** SDK call returns error, no ring on customer phone

    **Checklist:**

    * Verify ARI is enabled: `asterisk -rx "http show status"`
    * Check ARI credentials in vault: `ari_url`, `ari_user`, `ari_password`
    * Verify endpoint format: `PJSIP/trunk/number` or `PJSIP/number`
    * Check ARI URL is reachable from Rapida: must not be behind NAT without port forwarding
    * Review Asterisk CLI: `asterisk -rvvv` for ARI request logs
  </Accordion>

  <Accordion title="RAPIDA_CONTEXT_ID Empty in Outbound Dialplan">
    **Symptoms:** Outbound call connects but AudioSocket/WebSocket has no context

    **Checklist:**

    * Verify ARI channel variables are configured: `{"variables": {"RAPIDA_CONTEXT_ID": "..."}}`
    * Check the dialplan references `${RAPIDA_CONTEXT_ID}` (exact case)
    * Verify deployment options include `context` and `extension`
  </Accordion>
</AccordionGroup>

### Debug Commands

```bash theme={null}
# Check modules
asterisk -rx "module show like audiosocket"
asterisk -rx "module show like chan_websocket"

# Enable verbose debugging
asterisk -rx "core set debug 5"

# Monitor active channels
asterisk -rx "core show channels verbose"

# Check ARI status
asterisk -rx "http show status"

# View dialplan
asterisk -rx "dialplan show rapida-inbound"

# Test network connectivity
nc -zv socket-01.in.rapida.ai 4573   # AudioSocket
curl -I https://websocket-01.in.rapida.ai  # HTTPS/WebSocket
```

***

## High Availability

### Multi-Node Deployment

```mermaid theme={null}
graph TB
    subgraph Asterisk["Asterisk Cluster"]
        A1["Asterisk Primary"]
        A2["Asterisk Standby"]
    end

    subgraph LB["Load Balancer"]
        L4["TCP L4 (port 4573)"]
        L7["HTTPS L7 (port 443)"]
    end

    subgraph Rapida["Rapida Cluster"]
        R1["Node 1"]
        R2["Node 2"]
        R3["Node 3"]
        REDIS["Redis (shared)"]
    end

    A1 --> L4
    A1 --> L7
    A2 --> L4
    A2 --> L7
    L4 --> R1
    L4 --> R2
    L4 --> R3
    L7 --> R1
    L7 --> R2
    L7 --> R3
    R1 --> REDIS
    R2 --> REDIS
    R3 --> REDIS
```

**Dialplan with failover (AudioSocket):**

```ini theme={null}
[rapida-inbound-ha]
exten => _X.,1,Answer()
 same => n,Set(CHANNEL(audioreadformat)=slin)
 same => n,Set(CHANNEL(audiowriteformat)=slin)
 same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
 same => n,GotoIf($["${CTX}" = ""]?error)
 same => n,AudioSocket(${CTX},rapida-primary:4573)
 same => n,GotoIf($["${AUDIOSOCKET_STATUS}" = "FAILED"]?failover)
 same => n,Hangup()
 same => n(failover),AudioSocket(${CTX},rapida-secondary:4573)
 same => n,Hangup()
 same => n(error),Playback(an-error-has-occurred)
 same => n,Hangup()
```

***

## API Reference

### Inbound Webhook

```http theme={null}
GET /v1/talk/asterisk/call/{assistantId}
```

| Parameter     | Location        | Required | Description                |
| ------------- | --------------- | -------- | -------------------------- |
| `assistantId` | Path            | Yes      | Rapida assistant ID        |
| `from`        | Query           | Yes      | Caller phone number        |
| `x-api-key`   | Query or Header | Yes      | API key for authentication |
| `channel_id`  | Query           | No       | Asterisk channel ID        |

**Response:** Plain text `contextId` (UUID)

### WebSocket Media Endpoint

```http theme={null}
GET /v1/talk/asterisk/ctx/{contextId}
Upgrade: websocket
```

| Parameter   | Location | Required | Description                      |
| ----------- | -------- | -------- | -------------------------------- |
| `contextId` | Path     | Yes      | Context ID from webhook response |
| `x-api-key` | Query    | Yes      | API key for authentication       |

### Status Callback

```http theme={null}
POST /v1/talk/asterisk/ctx/{contextId}/event
```

Receives ARI-style JSON events with a `type` field.

***

## Related Resources

<CardGroup>
  <Card title="Voice Deployment Options" icon="phone" href="/voice-deployment-options/phone">
    Overview of all voice deployment channels
  </Card>

  <Card title="Create an Assistant" icon="bot" href="/assistants/create-assistant">
    Build your voice AI assistant
  </Card>

  <Card title="Webhooks" icon="link-2" href="/assistants/webhook/overview">
    Configure event notifications
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/call/create-call">
    Call API documentation
  </Card>
</CardGroup>


# Exotel
Source: https://doc.rapida.ai/integrations/telephony/exotel

Connect your Exotel phone numbers to Rapida AI for inbound and outbound voice AI conversations.

Exotel is a cloud telephony platform widely used across India and Southeast Asia, offering programmable voice and messaging APIs. Rapida integrates with Exotel to enable AI-powered phone conversations using Exotel's media streaming capabilities.

<Info>
  Exotel is particularly well-suited for businesses operating in India and SEA, offering local virtual numbers, regulatory compliance, and reliable connectivity in those regions.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant Exotel as Exotel Cloud
    participant API as Rapida Webhook API
    participant WS as Rapida Media Stream
    participant AI as AI Pipeline (STT → LLM → TTS)

    Caller->>Exotel: Dials your Exotel number
    Exotel->>API: POST /v1/talk/exotel/call/{assistantId}
    API->>API: Create conversation + save call context
    API-->>Exotel: Response with stream instructions

    rect rgb(230, 255, 230)
    Note over Exotel,AI: Media Streaming
    Exotel->>WS: Audio stream (bidirectional)
    WS->>AI: Audio → STT → LLM → TTS
    AI->>WS: TTS audio
    WS->>Exotel: Audio frames
    Exotel->>Caller: AI speaks
    end

    Caller->>Exotel: Hangup
    Exotel->>API: Status callback
```

***

## Prerequisites

<CardGroup>
  <Card title="Exotel Account" icon="phone">
    An active Exotel account with at least one virtual number and an Exotel App (applet)
  </Card>

  <Card title="Rapida Account" icon="key">
    An active Rapida account with a configured voice assistant
  </Card>
</CardGroup>

You will need your **Account SID**, **Client ID**, and **Client Secret**, which you can find in the [Exotel Dashboard](https://my.exotel.com/).

***

## Step 1: Set Up Provider Credentials

Store your Exotel API credentials in Rapida so the platform can authenticate with Exotel for outbound calls and webhook handling.

<Steps>
  <Step title="Navigate to External Integrations">
    Go to **Integration > Tools** in the Rapida dashboard. You will see a grid of available external integrations.

    <img alt="External Integrations Page" />
  </Step>

  <Step title="Select Exotel">
    Find the **Exotel** card and click **"Setup Credential"**.
  </Step>

  <Step title="Enter Your Exotel Credentials">
    <img alt="Exotel Credentials" />

    A modal will appear. Fill in the following fields:

    | Field             | Description                                                     | Where to Find                                               |
    | ----------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
    | **Key Name**      | A friendly name for this credential (e.g., "Production Exotel") | Your choice                                                 |
    | **Account SID**   | Your Exotel Account SID                                         | [Exotel Dashboard](https://my.exotel.com/) → Settings → API |
    | **Client ID**     | Your Exotel API Client ID                                       | Exotel Dashboard → Settings → API Credentials               |
    | **Client Secret** | Your Exotel API Client Secret                                   | Exotel Dashboard → Settings → API Credentials               |

    Click **"Configure"** to save.

    <Warning>
      Keep your Client Secret secure. It is used for API authentication and should not be shared publicly.
    </Warning>
  </Step>

  <Step title="Verify Connection">
    After saving, the Exotel card should display **"Connected"**. Click on it to see credential details, last updated time, and management options.
  </Step>
</Steps>

***

## Step 2: Configure Phone Deployment

With credentials saved, configure your assistant's phone deployment to use Exotel.

<Steps>
  <Step title="Open Your Assistant">
    Navigate to **Assistants** and select the assistant you want to deploy via phone.
  </Step>

  <Step title="Go to Phone Deployment">
    Click **"Deploy"** → **"Phone"** to open the phone deployment configuration page.
  </Step>

  <Step title="Select Exotel as Telephony Provider">
    In the **Telephony** section:

    1. Select **Exotel** from the telephony provider dropdown
    2. Choose the Exotel credential you created in Step 1 from the **Credential** dropdown
    3. Enter your **Phone** number — the Exotel virtual number for inbound calls and outbound caller ID
    4. Enter the **App ID** — your Exotel applet identifier that routes calls to Rapida

    <Tip>
      The **App ID** is the Exotel applet (flow) identifier. You create this in the Exotel dashboard and configure it to forward calls to Rapida's webhook URL.
    </Tip>
  </Step>

  <Step title="Configure Experience Settings">
    Set up the conversation experience:

    | Setting                  | Description                                    | Default            |
    | ------------------------ | ---------------------------------------------- | ------------------ |
    | **Greeting**             | The first message the AI speaks when answering | *(optional)*       |
    | **Error Message**        | Message spoken when an error occurs            | *(optional)*       |
    | **Idle Timeout**         | Seconds before prompting an idle caller        | `30`               |
    | **Idle Message**         | Message spoken when caller is idle             | `"Are you there?"` |
    | **Idle Timeout Retries** | How many times to retry before ending call     | `2`                |
    | **Max Call Duration**    | Maximum call length in seconds                 | `300`              |
  </Step>

  <Step title="Configure Audio Providers">
    Select your **Speech-to-Text** (STT) and **Text-to-Speech** (TTS) providers. These determine how audio is transcribed and synthesized during the call.
  </Step>

  <Step title="Save Deployment">
    Click **"Deploy"** to save. Your assistant is now ready to handle phone calls via Exotel.
  </Step>
</Steps>

***

## Step 3: Configure Your Exotel App

Point your Exotel app (applet) to Rapida so incoming calls are routed to your AI assistant.

<Steps>
  <Step title="Open Exotel Dashboard">
    Go to the [Exotel Dashboard](https://my.exotel.com/) and navigate to **App Bazaar** or **Flows**.
  </Step>

  <Step title="Create or Edit an App">
    Create a new app or edit an existing one. Configure the app to connect incoming calls to an external URL.

    Set the **webhook URL** to:

    ```
    https://websocket-01.in.rapida.ai/v1/talk/exotel/call/{your-assistant-id}?x-api-key={your-api-key}
    ```

    Replace `{your-assistant-id}` with your Rapida assistant ID.
  </Step>

  <Step title="Link Phone Number">
    Assign your Exotel virtual number to this app so inbound calls are routed through it.
  </Step>

  <Step title="Save">
    Save the app configuration. Your Exotel number is now connected to Rapida.
  </Step>
</Steps>

***

## Making Outbound Calls

Once your phone deployment is configured, you can initiate outbound calls using the Rapida API or SDKs.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from rapida import Rapida

    client = Rapida(api_key="rpd-xxx-your-key")

    call = client.calls.create(
        assistant_id=123456789,
        to_number="+919876543210",
        from_number="+911234567890",  # optional, uses deployment default
        metadata={"campaign": "follow-up"},
    )

    print(f"Call queued: conversation_id={call.conversation.id}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { Rapida } from 'rapida';

    const client = new Rapida({ apiKey: 'rpd-xxx-your-key' });

    const call = await client.calls.create({
      assistantId: 123456789,
      toNumber: '+919876543210',
      fromNumber: '+911234567890',
      metadata: { campaign: 'follow-up' },
    });

    console.log(`Call queued: ${call.conversation.id}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.rapida.ai/v1/talk/call \
      -H "Authorization: Bearer rpd-xxx-your-key" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+919876543210",
        "from_number": "+911234567890",
        "metadata": { "campaign": "follow-up" }
      }'
    ```
  </Tab>
</Tabs>

***

## Features

| Feature                   | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| **Inbound Calls**         | Customers call your Exotel number and speak with your AI assistant |
| **Outbound Calls**        | Initiate calls programmatically via SDK or API                     |
| **Real-time Streaming**   | Bidirectional audio via Exotel media streams                       |
| **Call Recording**        | Automatic conversation capture for review and compliance           |
| **India & SEA Numbers**   | Local virtual numbers for Indian and Southeast Asian markets       |
| **Number Masking**        | Protect customer and agent phone numbers during calls              |
| **Regulatory Compliance** | Compliant with TRAI and regional telecom regulations               |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Calls don't reach Rapida">
    * Verify the webhook URL in your Exotel App configuration
    * Ensure the URL uses `https://` and the correct assistant ID
    * Confirm the phone number is assigned to the correct Exotel App
  </Accordion>

  <Accordion title="One-way audio or no audio">
    * Verify your Exotel credential (Account SID, Client ID, Client Secret) is correct in Rapida
    * Check that your STT and TTS providers are configured in the phone deployment
    * Ensure the App ID in your phone deployment matches the Exotel app
  </Accordion>

  <Accordion title="Outbound calls fail">
    * Verify the Exotel credential is connected in **Integration > Tools**
    * Ensure the `from_number` is a valid Exotel number assigned to your account
    * Check that the phone deployment is configured and saved with the correct App ID
  </Accordion>

  <Accordion title="App ID issues">
    * The App ID should match the Exotel applet/flow identifier exactly
    * Verify the app is active and not paused in the Exotel dashboard
    * Ensure the app has the correct webhook URL configured
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup>
  <Card title="Create an Assistant" icon="bot" href="/assistants/create-assistant">
    Build your voice AI assistant
  </Card>

  <Card title="Phone Deployment" icon="phone" href="/voice-deployment-options/phone">
    Overview of phone deployment options
  </Card>

  <Card title="Outbound Call API" icon="code" href="/api-reference/call/create-call">
    API reference for creating calls
  </Card>

  <Card title="Conversation Logs" icon="list" href="/activity/conversation-logs">
    View call history and transcripts
  </Card>
</CardGroup>

For more information on Exotel's platform, visit the [Exotel Developer Documentation](https://developer.exotel.com/).


# SIP Trunk
Source: https://doc.rapida.ai/integrations/telephony/sip

Connect any SIP-compatible PBX, carrier, or VoIP provider to Rapida AI for voice conversations.

SIP (Session Initiation Protocol) Trunking provides a direct connection between your telephony infrastructure and Rapida. This is ideal for organizations that already use a SIP-compatible PBX (such as FreeSWITCH, Kamailio, or hosted SIP providers) and want to connect their existing phone lines to an AI voice assistant without relying on a specific cloud telephony vendor.

<Info>
  SIP Trunk is a **bring-your-own-carrier** option. Rapida runs a native SIP server that accepts inbound SIP INVITE requests and establishes RTP media sessions directly. This provides the lowest latency path for voice AI interactions.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant PBX as Your SIP PBX / Carrier
    participant SIP as Rapida SIP Server
    participant AI as AI Pipeline (STT → LLM → TTS)

    Caller->>PBX: Dials phone number
    PBX->>SIP: SIP INVITE (via configured trunk)
    SIP->>SIP: Authenticate + resolve assistant
    SIP-->>PBX: 200 OK (SDP with RTP port)

    rect rgb(230, 255, 230)
    Note over PBX,AI: RTP Media Session
    PBX->>SIP: RTP audio stream
    SIP->>AI: Audio → STT → LLM → TTS
    AI->>SIP: TTS audio
    SIP->>PBX: RTP audio frames
    PBX->>Caller: AI speaks
    end

    Caller->>PBX: Hangup
    PBX->>SIP: SIP BYE
    SIP->>SIP: End conversation + cleanup
```

***

## Prerequisites

<CardGroup>
  <Card title="SIP Infrastructure" icon="server">
    A SIP-compatible PBX, carrier, or VoIP provider that can send calls to an external SIP URI
  </Card>

  <Card title="Rapida Account" icon="key">
    An active Rapida account with a configured voice assistant
  </Card>
</CardGroup>

You will need:

* Your SIP trunk provider's **SIP URI** (e.g., `sip:trunk.provider.com:5060`)
* Optional **SIP Username** and **Password** if your trunk requires authentication

***

## Step 1: Set Up Provider Credentials

Store your SIP trunk credentials in Rapida so the platform can authenticate with your SIP infrastructure.

<Steps>
  <Step title="Navigate to External Integrations">
    Go to **Integration > Tools** in the Rapida dashboard. You will see a grid of available external integrations.

    <img alt="External Integrations Page" />
  </Step>

  <Step title="Select SIP Trunk">
    Find the **SIP Trunk** card and click **"Setup Credential"**.
  </Step>

  <Step title="Enter Your SIP Credentials">
    A modal will appear. Fill in the following fields:

    | Field            | Description                                                  | Required |
    | ---------------- | ------------------------------------------------------------ | -------- |
    | **Key Name**     | A friendly name for this credential (e.g., "Office PBX")     | Yes      |
    | **SIP URI**      | The SIP trunk endpoint (e.g., `sip:trunk.provider.com:5060`) | Yes      |
    | **SIP Username** | Authentication username for the SIP trunk                    | No       |
    | **SIP Password** | Authentication password for the SIP trunk                    | No       |

    Click **"Configure"** to save.

    <Tip>
      If your SIP provider uses IP-based authentication (allow-listing Rapida's IP), you can leave the username and password fields empty.
    </Tip>
  </Step>

  <Step title="Verify Connection">
    After saving, the SIP Trunk card should display **"Connected"**. Click on it to see credential details, last updated time, and management options.
  </Step>
</Steps>

***

## Step 2: Configure Phone Deployment

With credentials saved, configure your assistant's phone deployment to use SIP.

<Steps>
  <Step title="Open Your Assistant">
    Navigate to **Assistants** and select the assistant you want to deploy via phone.
  </Step>

  <Step title="Go to Phone Deployment">
    Click **"Deploy"** → **"Phone"** to open the phone deployment configuration page.
  </Step>

  <Step title="Select SIP Trunk as Telephony Provider">
    In the **Telephony** section:

    1. Select **SIP Trunk** from the telephony provider dropdown
    2. Choose the SIP credential you created in Step 1 from the **Credential** dropdown
    3. Enter the **Caller ID** — the phone number to display for outbound calls (e.g., `+15551234567`)
  </Step>

  <Step title="Configure Experience Settings">
    Set up the conversation experience:

    | Setting                  | Description                                    | Default            |
    | ------------------------ | ---------------------------------------------- | ------------------ |
    | **Greeting**             | The first message the AI speaks when answering | *(optional)*       |
    | **Error Message**        | Message spoken when an error occurs            | *(optional)*       |
    | **Idle Timeout**         | Seconds before prompting an idle caller        | `30`               |
    | **Idle Message**         | Message spoken when caller is idle             | `"Are you there?"` |
    | **Idle Timeout Retries** | How many times to retry before ending call     | `2`                |
    | **Max Call Duration**    | Maximum call length in seconds                 | `300`              |
  </Step>

  <Step title="Configure Audio Providers">
    Select your **Speech-to-Text** (STT) and **Text-to-Speech** (TTS) providers. These determine how audio is transcribed and synthesized during the call.
  </Step>

  <Step title="Save Deployment">
    Click **"Deploy"** to save. Your assistant is now ready to handle phone calls via SIP.
  </Step>
</Steps>

***

## Step 3: Configure Your PBX / SIP Provider

Route calls from your PBX or SIP carrier to Rapida's SIP server.

<Steps>
  <Step title="Create a SIP Trunk in Your PBX">
    In your PBX admin panel (FreeSWITCH, Asterisk, Kamailio, or hosted provider), create a new SIP trunk pointing to Rapida's SIP endpoint.

    **Rapida SIP Server:**

    ```
    sip:sip-01.in.rapida.ai:5060
    ```

    Configure your trunk with:

    * **Outbound Proxy**: `sip-01.in.rapida.ai:5060`
    * **Transport**: UDP or TCP
    * **Codec**: G.711 μ-law (PCMU) preferred, G.711 A-law (PCMA) supported
  </Step>

  <Step title="Create a Dial Plan Rule">
    Add a dial plan entry that routes specific numbers or patterns to the Rapida SIP trunk.

    **FreeSWITCH example:**

    ```xml theme={null}
    <extension name="rapida-ai">
      <condition field="destination_number" expression="^(5551234567)$">
        <action application="bridge" data="sofia/external/sip:did-$1@sip-01.in.rapida.ai:5060"/>
      </condition>
    </extension>
    ```

    **Asterisk example (extensions.conf):**

    ```ini theme={null}
    [rapida-trunk]
    exten => _X.,1,Dial(SIP/did-${EXTEN}@rapida-trunk)
    ```
  </Step>

  <Step title="Verify Routing">
    Place a test call to confirm the call reaches Rapida and the AI assistant answers.
  </Step>
</Steps>

***

## Inbound SIP URI Routing

Rapida routes inbound SIP calls from the user portion of the request URI. The `To` URI is used first; if it has no user, Rapida falls back to the `From` URI.

Accepted inbound destination formats:

| Format                                  | Example                                         | Resolution                                                                         |
| --------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
| `sip:agent-{assistantID}@{host}:{port}` | `sip:agent-123456789@sip-01.in.rapida.ai:5060`  | Routes directly by numeric assistant ID                                            |
| `sip:did-{did}@{host}:{port}`           | `sip:did-+15551234567@sip-01.in.rapida.ai:5060` | Looks up the active SIP phone deployment whose phone value exactly matches `{did}` |
| `sip:{did}@{host}:{port}`               | `sip:+15551234567@sip-01.in.rapida.ai:5060`     | Same DID lookup, without the `did-` prefix                                         |

The same route user forms are accepted with `sips:` when the SIP listener is configured for TLS.

<Note>
  The DID value is matched exactly against the phone number stored on the assistant's active SIP phone deployment. `+15551234567` and `15551234567` are different route values.
</Note>

<Warning>
  Credential-style users such as `sip:{assistantID}:{apiKey}@host` are not accepted for inbound routing. Use `agent-{assistantID}`, `did-{did}`, or the raw DID form.
</Warning>

***

## Making Outbound Calls

Once your phone deployment is configured, you can initiate outbound calls through your SIP trunk using the Rapida API or SDKs.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from rapida import Rapida

    client = Rapida(api_key="rpd-xxx-your-key")

    call = client.calls.create(
        assistant_id=123456789,
        to_number="+15551234567",
        metadata={"campaign": "follow-up"},
    )

    print(f"Call queued: conversation_id={call.conversation.id}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { Rapida } from 'rapida';

    const client = new Rapida({ apiKey: 'rpd-xxx-your-key' });

    const call = await client.calls.create({
      assistantId: 123456789,
      toNumber: '+15551234567',
      metadata: { campaign: 'follow-up' },
    });

    console.log(`Call queued: ${call.conversation.id}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.rapida.ai/v1/talk/call \
      -H "Authorization: Bearer rpd-xxx-your-key" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+15551234567",
        "metadata": { "campaign": "follow-up" }
      }'
    ```
  </Tab>
</Tabs>

***

## Features

| Feature                    | Description                                                                    |
| -------------------------- | ------------------------------------------------------------------------------ |
| **Bring Your Own Carrier** | Use any SIP-compatible provider or on-premise PBX                              |
| **Direct SIP Connection**  | Native SIP INVITE/BYE handling with RTP media — no intermediary cloud provider |
| **Low Latency**            | Direct RTP audio path minimizes round-trip delay                               |
| **Inbound Calls**          | Accept calls routed from your PBX to the AI assistant                          |
| **Outbound Calls**         | Initiate calls programmatically via SDK or API through your SIP trunk          |
| **Call Recording**         | Automatic conversation capture for review and compliance                       |
| **Codec Support**          | G.711 μ-law (PCMU), G.711 A-law (PCMA)                                         |
| **Flexible Auth**          | Digest authentication or IP-based allow-listing                                |

***

## Supported PBX / Providers

SIP Trunk works with any standard SIP-compliant system, including:

| System                 | Type                                             |
| ---------------------- | ------------------------------------------------ |
| **FreeSWITCH**         | Open-source softswitch                           |
| **Asterisk**           | Open-source PBX (also has dedicated integration) |
| **Kamailio**           | SIP proxy/router                                 |
| **Twilio Elastic SIP** | Cloud SIP trunking                               |
| **Vonage SIP Connect** | Cloud SIP trunking                               |
| **Bandwidth**          | Cloud SIP trunking                               |
| **Telnyx**             | Cloud SIP trunking                               |
| **SignalWire**         | Cloud SIP trunking                               |

<Tip>
  If you're using Twilio, Vonage, Exotel, or Asterisk, consider using the dedicated integrations for those providers — they offer additional features like webhook-based call control and provider-specific optimizations.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="SIP INVITE rejected or no response">
    * Verify the SIP URI in your credential is correct and reachable
    * Check that your PBX can route to `sip-01.in.rapida.ai:5060` (firewall/NAT rules)
    * If using authentication, ensure username and password are correct
    * Try both UDP and TCP transport if one doesn't work
  </Accordion>

  <Accordion title="One-way audio or no audio">
    * Check RTP port ranges — ensure your firewall allows UDP traffic for RTP media
    * Verify codec negotiation — Rapida supports G.711 μ-law (PCMU) and G.711 A-law (PCMA)
    * If behind NAT, ensure your PBX has proper STUN/TURN or external media IP configuration
    * Verify STT and TTS providers are configured in the phone deployment
  </Accordion>

  <Accordion title="Outbound calls fail">
    * Verify the SIP credential is connected in **Integration > Tools**
    * Ensure the phone deployment is configured and saved
    * Check that your SIP trunk allows outbound calls from Rapida's IP
  </Accordion>

  <Accordion title="Audio quality issues">
    * Use a wired network connection for your PBX when possible
    * Prefer G.711 μ-law (PCMU) codec for compatibility
    * Minimize network hops between your PBX and Rapida
    * Check for packet loss or jitter on the RTP path using network monitoring tools
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup>
  <Card title="Create an Assistant" icon="bot" href="/assistants/create-assistant">
    Build your voice AI assistant
  </Card>

  <Card title="Phone Deployment" icon="phone" href="/voice-deployment-options/phone">
    Overview of phone deployment options
  </Card>

  <Card title="Asterisk Integration" icon="server" href="/integrations/telephony/asterisk">
    Dedicated Asterisk PBX integration with AudioSocket
  </Card>

  <Card title="Conversation Logs" icon="list" href="/activity/conversation-logs">
    View call history and transcripts
  </Card>
</CardGroup>


# Twilio
Source: https://doc.rapida.ai/integrations/telephony/twilio

Connect your Twilio phone numbers to Rapida AI for inbound and outbound voice AI conversations.

Twilio is a cloud communications platform that provides programmable voice, messaging, and video services. Rapida integrates with Twilio to enable AI-powered phone conversations — both inbound (customers call your Twilio number) and outbound (your assistant calls customers).

<Info>
  Twilio uses **WebSocket media streams** for real-time audio. When a call connects, Twilio opens a WebSocket to Rapida carrying μ-law encoded audio at 8kHz. Rapida handles all codec conversion and resampling transparently.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant Twilio as Twilio Cloud
    participant API as Rapida Webhook API
    participant WS as Rapida WebSocket
    participant AI as AI Pipeline (STT → LLM → TTS)

    Caller->>Twilio: Dials your Twilio number
    Twilio->>API: POST /v1/talk/twilio/call/{assistantId}
    API->>API: Create conversation + save call context
    API-->>Twilio: TwiML (Connect → Stream)

    rect rgb(230, 255, 230)
    Note over Twilio,AI: Media Streaming
    Twilio->>WS: WebSocket connect (μ-law audio)
    WS->>AI: Audio → STT → LLM → TTS
    AI->>WS: TTS audio
    WS->>Twilio: μ-law audio
    Twilio->>Caller: AI speaks
    end

    Caller->>Twilio: Hangup
    Twilio->>API: Status callback
```

***

## Prerequisites

<CardGroup>
  <Card title="Twilio Account" icon="phone">
    An active Twilio account with at least one phone number
  </Card>

  <Card title="Rapida Account" icon="key">
    An active Rapida account with a configured voice assistant
  </Card>
</CardGroup>

You will need your **Twilio Account SID** and **Auth Token**, which you can find on the [Twilio Console dashboard](https://console.twilio.com/).

***

## Step 1: Set Up Provider Credentials

First, store your Twilio API credentials in Rapida so the platform can authenticate with Twilio for outbound calls and webhook validation.

<Steps>
  <Step title="Navigate to External Integrations">
    Go to **Integration > Tools** in the Rapida dashboard. You will see a grid of available external integrations.

    <img alt="External Integrations Page" />
  </Step>

  <Step title="Select Twilio">
    Find the **Twilio** card and click **"Setup Credential"**.
  </Step>

  <Step title="Enter Your Twilio Credentials">
    <img alt="Twilio Credentials" />

    A modal will appear. Fill in the following fields:

    | Field             | Description                                                     | Where to Find                                               |
    | ----------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
    | **Key Name**      | A friendly name for this credential (e.g., "Production Twilio") | Your choice                                                 |
    | **Account Token** | Your Twilio Auth Token                                          | [Twilio Console](https://console.twilio.com/) → Auth Token  |
    | **Account SID**   | Your Twilio Account SID                                         | [Twilio Console](https://console.twilio.com/) → Account SID |

    Click **"Configure"** to save.
  </Step>

  <Step title="Verify Connection">
    After saving, the Twilio card should display **"Connected"**. Click on it to see credential details, last updated time, and management options.
  </Step>
</Steps>

***

## Step 2: Configure Phone Deployment

With credentials saved, configure your assistant's phone deployment to use Twilio.

<Steps>
  <Step title="Open Your Assistant">
    Navigate to **Assistants** and select the assistant you want to deploy via phone.
  </Step>

  <Step title="Go to Phone Deployment">
    Click **"Deploy"** → **"Phone"** to open the phone deployment configuration page.
  </Step>

  <Step title="Select Twilio as Telephony Provider">
    In the **Telephony** section:

    1. Select **Twilio** from the telephony provider dropdown
    2. Choose the Twilio credential you created in Step 1 from the **Credential** dropdown
    3. Enter your **Phone** number — this is the Twilio phone number that will receive inbound calls and serve as the caller ID for outbound calls (e.g., `+15551234567`)
  </Step>

  <Step title="Configure Experience Settings">
    Set up the conversation experience:

    | Setting                  | Description                                    | Default            |
    | ------------------------ | ---------------------------------------------- | ------------------ |
    | **Greeting**             | The first message the AI speaks when answering | *(optional)*       |
    | **Error Message**        | Message spoken when an error occurs            | *(optional)*       |
    | **Idle Timeout**         | Seconds before prompting an idle caller        | `30`               |
    | **Idle Message**         | Message spoken when caller is idle             | `"Are you there?"` |
    | **Idle Timeout Retries** | How many times to retry before ending call     | `2`                |
    | **Max Call Duration**    | Maximum call length in seconds                 | `300`              |
  </Step>

  <Step title="Configure Audio Providers">
    Select your **Speech-to-Text** (STT) and **Text-to-Speech** (TTS) providers. These determine how audio is transcribed and synthesized during the call.

    <Note>
      For Twilio calls, audio arrives in **μ-law 8kHz** format. Rapida automatically resamples to 16kHz for the STT provider and converts TTS output back to μ-law for Twilio.
    </Note>
  </Step>

  <Step title="Save Deployment">
    Click **"Deploy"** to save. Your assistant is now ready to handle phone calls via Twilio.
  </Step>
</Steps>

***

## Step 3: Configure Your Twilio Phone Number

Point your Twilio phone number's webhook to Rapida so incoming calls are routed to your AI assistant.

<Steps>
  <Step title="Open Twilio Console">
    Go to [Twilio Console → Phone Numbers → Active Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming) and select your phone number.
  </Step>

  <Step title="Set Voice Webhook">
    Under **Voice Configuration**, set:

    | Field               | Value                                                                                                |
    | ------------------- | ---------------------------------------------------------------------------------------------------- |
    | **A call comes in** | Webhook                                                                                              |
    | **URL**             | `https://websocket-01.in.rapida.ai/v1/talk/twilio/call/{your-assistant-id}?x-api-key={your-api-key}` |
    | **HTTP Method**     | `POST`                                                                                               |

    Replace `{your-assistant-id}` with your Rapida assistant ID.
  </Step>

  <Step title="Set Status Callback (Optional)">
    To receive call lifecycle events (ringing, answered, completed):

    | Field                      | Value                                                                                             |
    | -------------------------- | ------------------------------------------------------------------------------------------------- |
    | **Status Callback URL**    | `https://websocket-01.in.rapida.ai/v1/talk/twilio/ctx/{contextId}/event?x-api-key={your-api-key}` |
    | **Status Callback Events** | `initiated`, `ringing`, `answered`, `completed`                                                   |

    <Note>
      The status callback URL uses a `contextId` returned during the call setup. Twilio sends events to this URL automatically when configured in TwiML.
    </Note>
  </Step>

  <Step title="Save">
    Click **Save** in the Twilio console. Your phone number is now connected to Rapida.
  </Step>
</Steps>

***

## Making Outbound Calls

Once your phone deployment is configured, you can initiate outbound calls using the Rapida API or SDKs.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from rapida import Rapida

    client = Rapida(api_key="rpd-xxx-your-key")

    call = client.calls.create(
        assistant_id=123456789,
        to_number="+15551234567",
        from_number="+15559876543",  # optional, uses deployment default
        metadata={"campaign": "follow-up"},
    )

    print(f"Call queued: conversation_id={call.conversation.id}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { Rapida } from 'rapida';

    const client = new Rapida({ apiKey: 'rpd-xxx-your-key' });

    const call = await client.calls.create({
      assistantId: 123456789,
      toNumber: '+15551234567',
      fromNumber: '+15559876543',
      metadata: { campaign: 'follow-up' },
    });

    console.log(`Call queued: ${call.conversation.id}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.rapida.ai/v1/talk/call \
      -H "Authorization: Bearer rpd-xxx-your-key" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+15551234567",
        "from_number": "+15559876543",
        "metadata": { "campaign": "follow-up" }
      }'
    ```
  </Tab>
</Tabs>

***

## Features

| Feature                 | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| **Inbound Calls**       | Customers call your Twilio number and speak with your AI assistant |
| **Outbound Calls**      | Initiate calls programmatically via SDK or API                     |
| **Real-time Streaming** | Bidirectional audio via Twilio Media Streams (WebSocket)           |
| **Call Recording**      | Automatic conversation capture for review and compliance           |
| **Status Callbacks**    | Receive call lifecycle events (ringing, answered, completed)       |
| **WhatsApp**            | Send and receive WhatsApp messages via Twilio                      |
| **Global Numbers**      | Use Twilio phone numbers from 100+ countries                       |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Calls go to voicemail instead of Rapida">
    * Verify the webhook URL in your Twilio phone number configuration
    * Ensure the URL uses `https://` and the correct assistant ID
    * Check that your Rapida API key is valid
  </Accordion>

  <Accordion title="One-way audio or no audio">
    * Verify your Twilio credential (Account SID + Auth Token) is correct in Rapida
    * Check that your STT and TTS providers are configured in the phone deployment
    * Ensure the assistant has an active version with a valid LLM provider
  </Accordion>

  <Accordion title="Outbound calls fail">
    * Verify the Twilio credential is connected in **Integration > Tools**
    * Ensure the `from_number` is a valid Twilio phone number in your account
    * Check that the phone deployment is configured and saved
  </Accordion>

  <Accordion title="Status callbacks not received">
    * Ensure the status callback URL is configured in Twilio console
    * Verify the URL format: `https://websocket-01.in.rapida.ai/v1/talk/twilio/ctx/{contextId}/event?x-api-key={your-api-key}`
    * Check Twilio's [Debugger](https://console.twilio.com/us1/monitor/logs/debugger) for webhook errors
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup>
  <Card title="Create an Assistant" icon="bot" href="/assistants/create-assistant">
    Build your voice AI assistant
  </Card>

  <Card title="Phone Deployment" icon="phone" href="/voice-deployment-options/phone">
    Overview of phone deployment options
  </Card>

  <Card title="Outbound Call API" icon="code" href="/api-reference/call/create-call">
    API reference for creating calls
  </Card>

  <Card title="Conversation Logs" icon="list" href="/activity/conversation-logs">
    View call history and transcripts
  </Card>
</CardGroup>

For more information on Twilio's platform, visit the [Twilio Developer Documentation](https://www.twilio.com/docs).


# Vonage
Source: https://doc.rapida.ai/integrations/telephony/vonage

Connect your Vonage phone numbers to Rapida AI for inbound and outbound voice AI conversations.

Vonage (now part of Ericsson) is a cloud communications platform providing programmable voice, messaging, and video APIs. Rapida integrates with Vonage to enable AI-powered phone conversations using Vonage's WebSocket media streaming.

<Info>
  Vonage uses **WebSocket audio streams** for real-time media. When a call connects, Vonage opens a WebSocket to Rapida carrying linear PCM audio. Rapida handles all codec conversion and resampling transparently.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant Vonage as Vonage Cloud
    participant API as Rapida Webhook API
    participant WS as Rapida WebSocket
    participant AI as AI Pipeline (STT → LLM → TTS)

    Caller->>Vonage: Dials your Vonage number
    Vonage->>API: POST /v1/talk/vonage/call/{assistantId}
    API->>API: Create conversation + save call context
    API-->>Vonage: NCCO (Connect → WebSocket)

    rect rgb(230, 255, 230)
    Note over Vonage,AI: Media Streaming
    Vonage->>WS: WebSocket connect (linear PCM audio)
    WS->>AI: Audio → STT → LLM → TTS
    AI->>WS: TTS audio
    WS->>Vonage: Audio frames
    Vonage->>Caller: AI speaks
    end

    Caller->>Vonage: Hangup
    Vonage->>API: Status callback
```

***

## Prerequisites

<CardGroup>
  <Card title="Vonage Account" icon="phone">
    An active Vonage account with at least one phone number and a Vonage Application
  </Card>

  <Card title="Rapida Account" icon="key">
    An active Rapida account with a configured voice assistant
  </Card>
</CardGroup>

You will need your **Vonage Application ID** and **Private Key**, which you can find in the [Vonage API Dashboard](https://dashboard.nexmo.com/).

***

## Step 1: Set Up Provider Credentials

Store your Vonage API credentials in Rapida so the platform can authenticate with Vonage for outbound calls and webhook handling.

<Steps>
  <Step title="Navigate to External Integrations">
    Go to **Integration > Tools** in the Rapida dashboard. You will see a grid of available external integrations.

    <img alt="External Integrations Page" />
  </Step>

  <Step title="Select Vonage">
    Find the **Vonage** card and click **"Setup Credential"**.
  </Step>

  <Step title="Enter Your Vonage Credentials">
    <img alt="Vonage Credentials" />

    A modal will appear. Fill in the following fields:

    | Field              | Description                                                     | Where to Find                                                              |
    | ------------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
    | **Key Name**       | A friendly name for this credential (e.g., "Production Vonage") | Your choice                                                                |
    | **Application ID** | Your Vonage Application ID                                      | [Vonage Dashboard](https://dashboard.nexmo.com/) → Applications → Your App |
    | **Private Key**    | Your Vonage Application private key (full PEM content)          | Downloaded when creating the Vonage Application                            |

    Click **"Configure"** to save.

    <Warning>
      The private key is the full PEM file content, not just a token. It typically begins with `-----BEGIN RSA PRIVATE KEY-----`. Paste the entire contents.
    </Warning>
  </Step>

  <Step title="Verify Connection">
    After saving, the Vonage card should display **"Connected"**. Click on it to see credential details, last updated time, and management options.
  </Step>
</Steps>

***

## Step 2: Configure Phone Deployment

With credentials saved, configure your assistant's phone deployment to use Vonage.

<Steps>
  <Step title="Open Your Assistant">
    Navigate to **Assistants** and select the assistant you want to deploy via phone.
  </Step>

  <Step title="Go to Phone Deployment">
    Click **"Deploy"** → **"Phone"** to open the phone deployment configuration page.
  </Step>

  <Step title="Select Vonage as Telephony Provider">
    In the **Telephony** section:

    1. Select **Vonage** from the telephony provider dropdown
    2. Choose the Vonage credential you created in Step 1 from the **Credential** dropdown
    3. Enter your **Phone** number — the Vonage virtual number for inbound calls and outbound caller ID (e.g., `+15551234567`)
  </Step>

  <Step title="Configure Experience Settings">
    Set up the conversation experience:

    | Setting                  | Description                                    | Default            |
    | ------------------------ | ---------------------------------------------- | ------------------ |
    | **Greeting**             | The first message the AI speaks when answering | *(optional)*       |
    | **Error Message**        | Message spoken when an error occurs            | *(optional)*       |
    | **Idle Timeout**         | Seconds before prompting an idle caller        | `30`               |
    | **Idle Message**         | Message spoken when caller is idle             | `"Are you there?"` |
    | **Idle Timeout Retries** | How many times to retry before ending call     | `2`                |
    | **Max Call Duration**    | Maximum call length in seconds                 | `300`              |
  </Step>

  <Step title="Configure Audio Providers">
    Select your **Speech-to-Text** (STT) and **Text-to-Speech** (TTS) providers. These determine how audio is transcribed and synthesized during the call.
  </Step>

  <Step title="Save Deployment">
    Click **"Deploy"** to save. Your assistant is now ready to handle phone calls via Vonage.
  </Step>
</Steps>

***

## Step 3: Configure Your Vonage Application

Point your Vonage Application's webhook URLs to Rapida so incoming calls are routed to your AI assistant.

<Steps>
  <Step title="Open Vonage Dashboard">
    Go to [Vonage Dashboard → Applications](https://dashboard.nexmo.com/applications) and select your application.
  </Step>

  <Step title="Set Voice Webhooks">
    Under **Capabilities → Voice**, configure:

    | Field           | Value                                                                                                |
    | --------------- | ---------------------------------------------------------------------------------------------------- |
    | **Answer URL**  | `https://websocket-01.in.rapida.ai/v1/talk/vonage/call/{your-assistant-id}?x-api-key={your-api-key}` |
    | **Event URL**   | `https://websocket-01.in.rapida.ai/v1/talk/vonage/ctx/{contextId}/event?x-api-key={your-api-key}`    |
    | **HTTP Method** | `POST`                                                                                               |

    Replace `{your-assistant-id}` with your Rapida assistant ID.
  </Step>

  <Step title="Link Phone Number">
    Under **Numbers**, link your Vonage virtual number to this application so inbound calls are routed through it.
  </Step>

  <Step title="Save">
    Click **Save** in the Vonage dashboard. Your phone number is now connected to Rapida.
  </Step>
</Steps>

***

## Making Outbound Calls

Once your phone deployment is configured, you can initiate outbound calls using the Rapida API or SDKs.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from rapida import Rapida

    client = Rapida(api_key="rpd-xxx-your-key")

    call = client.calls.create(
        assistant_id=123456789,
        to_number="+15551234567",
        from_number="+15559876543",  # optional, uses deployment default
        metadata={"campaign": "follow-up"},
    )

    print(f"Call queued: conversation_id={call.conversation.id}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { Rapida } from 'rapida';

    const client = new Rapida({ apiKey: 'rpd-xxx-your-key' });

    const call = await client.calls.create({
      assistantId: 123456789,
      toNumber: '+15551234567',
      fromNumber: '+15559876543',
      metadata: { campaign: 'follow-up' },
    });

    console.log(`Call queued: ${call.conversation.id}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.rapida.ai/v1/talk/call \
      -H "Authorization: Bearer rpd-xxx-your-key" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+15551234567",
        "from_number": "+15559876543",
        "metadata": { "campaign": "follow-up" }
      }'
    ```
  </Tab>
</Tabs>

***

## Features

| Feature                 | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| **Inbound Calls**       | Customers call your Vonage number and speak with your AI assistant |
| **Outbound Calls**      | Initiate calls programmatically via SDK or API                     |
| **Real-time Streaming** | Bidirectional audio via Vonage WebSocket streams                   |
| **Call Recording**      | Automatic conversation capture for review and compliance           |
| **Status Callbacks**    | Receive call lifecycle events via Vonage event webhooks            |
| **Number Insight**      | Get detailed information about phone numbers                       |
| **Global Numbers**      | Use Vonage virtual numbers from 80+ countries                      |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Calls don't reach Rapida">
    * Verify the Answer URL in your Vonage Application settings
    * Ensure the URL uses `https://` and the correct assistant ID
    * Confirm the phone number is linked to the correct Vonage Application
  </Accordion>

  <Accordion title="One-way audio or no audio">
    * Verify your Vonage credential (Application ID + Private Key) is correct in Rapida
    * Ensure the private key is the complete PEM content
    * Check that your STT and TTS providers are configured in the phone deployment
  </Accordion>

  <Accordion title="Outbound calls fail">
    * Verify the Vonage credential is connected in **Integration > Tools**
    * Ensure the `from_number` is a valid Vonage number linked to your application
    * Check that the phone deployment is configured and saved
  </Accordion>

  <Accordion title="Event callbacks not received">
    * Ensure the Event URL is configured in Vonage Application settings
    * Verify the URL format includes the correct path
    * Check the [Vonage API Dashboard](https://dashboard.nexmo.com/) for webhook delivery logs
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup>
  <Card title="Create an Assistant" icon="bot" href="/assistants/create-assistant">
    Build your voice AI assistant
  </Card>

  <Card title="Phone Deployment" icon="phone" href="/voice-deployment-options/phone">
    Overview of phone deployment options
  </Card>

  <Card title="Outbound Call API" icon="code" href="/api-reference/call/create-call">
    API reference for creating calls
  </Card>

  <Card title="Conversation Logs" icon="list" href="/activity/conversation-logs">
    View call history and transcripts
  </Card>
</CardGroup>

For more information on Vonage's platform, visit the [Vonage API Developer Documentation](https://developer.vonage.com/).


# AWS Polly
Source: https://doc.rapida.ai/integrations/tts/aws-polly

Amazon Polly is a cloud-based text-to-speech service that synthesizes natural-sounding speech in dozens of languages and voices.

Amazon Polly converts text to lifelike speech using deep learning models. It offers standard neural voices and supports SSML for fine-grained control over speech output — ideal for telephony and IVR systems.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add AWS credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your AWS Access Key ID and Secret Access Key. The IAM role needs `AmazonPollyReadOnlyAccess` or a scoped `polly:SynthesizeSpeech` permission.
  </Step>

  <Step title="Select AWS Polly as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **AWS** as your Text-to-Speech provider.
  </Step>

  <Step title="Choose a voice and language">
    Polly offers 60+ voices across 30+ languages. Choose the voice that matches your assistant's target language and persona.
  </Step>
</Steps>

## Voice Types

| Type         | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| **Neural**   | Higher quality, more natural-sounding voices using a neural TTS engine |
| **Standard** | Concatenative synthesis — lower cost, suitable for basic use cases     |

Neural voices are recommended for production voice assistants.

## Popular Voices

| Voice ID  | Language     | Gender |
| --------- | ------------ | ------ |
| `Joanna`  | English (US) | Female |
| `Matthew` | English (US) | Male   |
| `Amy`     | English (UK) | Female |
| `Brian`   | English (UK) | Male   |
| `Léa`     | French       | Female |
| `Lupe`    | Spanish (US) | Female |

## SSML Support

Polly supports SSML tags for granular speech control:

```xml theme={null}
<speak>
  Welcome back, <emphasis level="strong">valued customer</emphasis>.
  Your appointment is scheduled for <say-as interpret-as="date" format="mdy">12/25/2025</say-as>.
  <break time="500ms"/>
  Is there anything else I can help you with?
</speak>
```

## Configuration Options

| Option        | Description                                               |
| ------------- | --------------------------------------------------------- |
| Region        | AWS region for Polly (e.g. `us-east-1`)                   |
| Voice ID      | Polly voice identifier                                    |
| Engine        | `neural` or `standard`                                    |
| Language code | BCP-47 language code (required for some bilingual voices) |
| Sample rate   | Output audio sample rate (8000 or 16000 Hz for telephony) |

## Notes

* Neural voices are not available in all AWS regions. Check the [Polly neural voice list](https://docs.aws.amazon.com/polly/latest/dg/ntts-voices-main.html).
* For telephony use cases, set sample rate to 8000 Hz to match PSTN audio formats.
* Pricing is per character synthesized. See [AWS Polly pricing](https://aws.amazon.com/polly/pricing/).

## Related

* [AWS Transcribe STT](/integrations/stt/aws-transcribe)
* [Azure Speech TTS](/integrations/tts/azure-speech-service)


# Azure Cognitive Services
Source: https://doc.rapida.ai/integrations/tts/azure-speech-service

Azure Cognitive Services Text-to-Speech provides natural-sounding voice synthesis with multiple languages and voices.

## Getting Started

To integrate Azure Cognitive Services with your Rapida application for text-to-speech (TTS) capabilities, follow these steps:

## Supported Models

### Text-to-Speech Voices

Azure Cognitive Services supports 400+ voices across multiple languages. Some popular voices include:

#### English Voices

| Voice Name          | Gender | Description                                |
| ------------------- | ------ | ------------------------------------------ |
| en-US-AriaNeural    | Female | Modern, natural-sounding US English female |
| en-US-GuyNeural     | Male   | Natural US English male voice              |
| en-GB-AmberNeural   | Female | British English female voice               |
| en-GB-AlfieNeural   | Male   | British English male voice                 |
| en-AU-NatashaNeural | Female | Australian English female                  |
| en-AU-WilliamNeural | Male   | Australian English male                    |

### Supported Languages

Azure supports text-to-speech in 50+ languages including:

* English (US, UK, Australian, Indian variants)
* Spanish, French, German, Italian, Dutch
* Mandarin, Cantonese, Japanese, Korean
* Hindi, Portuguese, Russian, Arabic, Hebrew
* Thai, Vietnamese, Polish, Swedish, and more

### Features

* **Neural Voices**: High-quality neural network-powered voices
* **Speaking Styles**: Different emotional tones (cheerful, empathetic, calm, etc.)
* **Pitch & Rate Control**: Fine-tune pitch and speaking rate
* **SSML Support**: Full SSML markup support for advanced control
* **Audio Formats**: Support for multiple audio formats and sample rates

## Prerequisites

* Have an Azure account
* Create an Azure Cognitive Services Speech resource
* Get your Subscription Key and Endpoint URL
* Note your resource region

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Azure Cognitive Services">
    On the Integrations page, find the Azure Cognitive Services provider card.

    Click the "Setup Credential" button for Azure Cognitive Services.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Azure Cognitive Services" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter Subscription Key: Input your Azure Subscription Key
    4. Enter Endpoint: Input your Azure Cognitive Services endpoint URL
    5. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Azure Cognitive Services provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Azure Cognitive Services provider credential is now set up for text-to-speech integration.

## Integration Features

* **400+ Neural Voices**: Extensive voice selection across multiple languages
* **Natural Quality**: High-quality neural speech synthesis
* **Multiple Languages**: Support for 50+ languages
* **Emotional Expression**: Different speaking styles and emotions
* **SSML Support**: Advanced markup language for precise control
* **Cost-Effective**: Pay-as-you-go pricing model
* **Enterprise Ready**: Compliance and security certifications

For more information, visit the [Azure Cognitive Services Speech documentation](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/).


# Cartesia Text-to-Speech
Source: https://doc.rapida.ai/integrations/tts/cartesia

Cartesia delivers advanced text-to-speech capabilities with ultra-realistic voice synthesis.

## Getting Started

To integrate Cartesia Text-to-Speech with your Rapida application, follow these steps:

## Supported Models

### Text-to-Speech Models

| Model Name    | Description                 | Use Case                           |
| ------------- | --------------------------- | ---------------------------------- |
| Sonic English | High-quality English voices | Professional TTS applications      |
| Bark Model    | Expressive speech synthesis | Creative and dynamic voice outputs |
| Tortoise TTS  | Ultra-realistic voices      | High-fidelity voice synthesis      |

### Supported Languages

Cartesia supports 20+ languages including:

* English (multiple accents)
* Spanish, French, German, Italian
* Portuguese, Russian, Polish, Dutch
* Japanese, Mandarin, Korean
* Hindi and other Indian languages
* And more

### Voice Features

* **Multiple Voice Personalities**: Choose from various voice options
* **Emotion Expression**: Control emotional tone and expressiveness
* **Pronunciation Control**: Define how specific words are pronounced
* **Speed Control**: Adjust speaking rate from slow to fast
* **Streaming Support**: Stream audio in real-time

## Prerequisites

* Have a Cartesia account (sign up at [https://cartesia.ai](https://cartesia.ai))
* Navigate to your API dashboard
* Generate an API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Cartesia">
    On the Integrations page, find the Cartesia provider card.

    Click the "Setup Credential" button for Cartesia.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Cartesia" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Cartesia API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Cartesia provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Cartesia Text-to-Speech provider credential is now set up.

## Integration Features

* **Ultra-Realistic Voices**: Advanced voice synthesis quality
* **20+ Languages**: Comprehensive language coverage
* **Multiple Voice Models**: Choose different TTS models
* **Expression Control**: Fine-tune emotional expression
* **Real-time Processing**: Low-latency audio generation
* **Streaming TTS**: Stream audio as it's being generated
* **Professional Quality**: Enterprise-grade voice synthesis

For more information, visit the [Cartesia documentation](https://www.cartesia.ai/).


# Custom Text-to-Speech
Source: https://doc.rapida.ai/integrations/tts/custom

Configure a custom WebSocket text-to-speech provider with credentials, audio settings, query parameters, request rules, response rules, and the Rapida DSL.

Custom Text-to-Speech lets you connect Rapida to a WebSocket speech synthesis service that is not available as a built-in TTS provider. You provide the provider endpoint, authentication headers, output audio format, and a JSON DSL that tells Rapida how to send assistant text and how to read provider audio, done, and error responses.

Use Custom TTS when your provider can receive text over WebSocket and return audio as one of the following:

* Binary WebSocket frames containing raw audio.
* JSON WebSocket messages containing base64-encoded audio.

**Provider identifier:** `custom-tts`

**API compatibility:** `websocket_v1`

<Info>
  Custom TTS is configured from credentials and assistant voice output settings. You do not need to write a new Rapida transformer when the provider protocol can be described with the DSL on this page.
</Info>

## Setup flow

<Steps>
  <Step title="Confirm the provider protocol">
    Custom TTS supports `websocket_v1`. Your provider must accept a WebSocket connection and return audio or status messages over that same connection.
  </Step>

  <Step title="Create the Custom TTS credential">
    Open **Credentials** or **Integrations > Models**, choose **Custom TTS**, and create a credential with `apiCompatibility`, `baseUrl`, and any required `headers`.
  </Step>

  <Step title="Select Custom TTS for voice output">
    Open the assistant or deployment voice settings, go to **Voice Output**, and select **Custom TTS** as the text-to-speech provider.
  </Step>

  <Step title="Set the output audio format">
    Choose the audio encoding and sample rate returned by your provider.

    Rapida interprets provider audio using these values, then resamples it to Rapida's internal audio format when needed.
  </Step>

  <Step title="Write the DSL configuration">
    Fill `speak.query_params`, `speak.request_rules`, and `speak.response_rules`.

    Query parameters build the provider WebSocket URL. Request rules map Rapida text lifecycle packets to outbound provider frames. Response rules map provider frames to audio, done, or error events.
  </Step>

  <Step title="Test speech and interruption">
    Run a test conversation. Confirm that audio plays, done events end the response cleanly, and interruption stops any queued provider audio.
  </Step>
</Steps>

## Credential fields

Create one credential for the external TTS provider.

| Field              | Required | Description                                                                                                                                                       |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiCompatibility` | No       | Selects the transport. Custom TTS supports `websocket_v1`. Defaults to `websocket_v1` when omitted.                                                               |
| `baseUrl`          | Yes      | WebSocket URL for your TTS service, for example `wss://tts.example.com/v1/speak`.                                                                                 |
| `headers`          | No       | Static header map sent during the WebSocket handshake. Use this for authorization and provider-required headers, for example `{"Authorization":"Bearer sk_..."}`. |

The runtime also accepts snake case credential keys: `api_compatibility` and `base_url`.

<Warning>
  Headers are static credential values. The DSL cannot template headers, read environment variables, sign requests, or change the WebSocket path dynamically.
</Warning>

## Assistant TTS arguments

These fields are configured on the assistant or deployment voice output provider. The UI stores them with the provider metadata, and the runtime reads the option keys shown below.

| Option key                | Required | Default    | Description                                                                                                                                                                   |
| ------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `speak.audio.encoding`    | Yes      | `LINEAR16` | Audio encoding expected from the provider. Rapida uses this when interpreting returned audio. Supported values are `LINEAR16` and `MuLaw8`.                                   |
| `speak.audio.sample_rate` | Yes      | `16000`    | Audio sample rate expected from the provider. Supported UI values are `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, and `48000`.                                       |
| `speak.query_params`      | No       | `{}`       | Flat JSON object appended to `baseUrl` as query parameters. Values can be static primitives or query DSL expressions.                                                         |
| `speak.request_rules`     | Yes      | None       | Ordered JSON array that maps Rapida packets to outbound provider messages. Must contain at least one rule with `when.packet` set to `text`.                                   |
| `speak.response_rules`    | Yes      | None       | Ordered JSON array that maps provider WebSocket frames to Rapida audio, done, or error events. Must contain at least one rule.                                                |
| `speak.voice.id`          | No       | Empty      | Optional provider voice identifier. When present, query params can read it with `{ "$var": "voice_id" }` and request rules can read it with `{ "$path": "config.voice.id" }`. |
| `speak.model`             | No       | Empty      | Optional provider model identifier. When present, query params can read it with `{ "$var": "model" }` and request rules can read it with `{ "$path": "config.model" }`.       |
| `speak.language`          | No       | Empty      | Optional provider language code. When present, query params can read it with `{ "$var": "language" }` and request rules can read it with `{ "$path": "config.language" }`.    |

<Note>
  The UI exposes the audio and DSL fields. `speak.voice.id`, `speak.model`, and `speak.language` are optional metadata keys for API-driven or imported configurations. If your provider needs fixed voice, model, or language values and those fields are not available in your UI, put the values directly in query params or request rules.
</Note>

<Info>
  When you work with raw assistant metadata, use the unprefixed custom TTS option keys, such as `speak.request_rules`. The UI may preserve other speaker-level settings under `speaker.*`, but the custom TTS DSL fields are the `speak.*` keys listed above.
</Info>

## DSL overview

Custom TTS has three DSL sections.

| Section          | Option key             | Purpose                                                                                                             |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Query parameters | `speak.query_params`   | Adds provider settings to the WebSocket URL, such as message ID, voice, model, language, encoding, and sample rate. |
| Request rules    | `speak.request_rules`  | Converts Rapida text lifecycle packets into provider WebSocket frames.                                              |
| Response rules   | `speak.response_rules` | Converts provider WebSocket frames into audio, done, or error events.                                               |

The DSL is intentionally small. It does not run JavaScript, call functions, perform regex matching, concatenate strings, perform compound conditions, read environment variables, or compute authentication signatures.

## Query parameters

Use `speak.query_params` when your provider expects configuration in the WebSocket URL.

```json theme={null}
{
  "voice": { "$var": "voice_id" },
  "model": { "$var": "model" },
  "message_id": { "$var": "message_id" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

### Query variable reference

Query parameter expressions can use `$var` to read these variables.

| Variable      | Source value                            | Example output |
| ------------- | --------------------------------------- | -------------- |
| `message_id`  | Current synthesis message or context ID | `msg_123`      |
| `voice_id`    | `speak.voice.id`                        | `voice_123`    |
| `model`       | `speak.model`                           | `sonic-2`      |
| `language`    | `speak.language`                        | `en-US`        |
| `encoding`    | `speak.audio.encoding`                  | `LINEAR16`     |
| `sample_rate` | `speak.audio.sample_rate`               | `16000`        |

### Query parameter rules

* `speak.query_params` must be a JSON object.
* The object must be flat. A query parameter value cannot be a nested object or array unless that object is a supported DSL expression.
* Each rendered value must be a primitive supported by the UI validator: string, number, or boolean.
* Existing query parameters in `baseUrl` are preserved unless `speak.query_params` renders the same key.
* A key that starts with `$` is treated as an unsupported operator and is rejected.
* `text` is not a supported query parameter variable. Use `packet.text` in request rules.

This configuration:

```json theme={null}
{
  "voice": "narrator-1",
  "message_id": { "$var": "message_id" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

can produce a provider URL like:

```text theme={null}
wss://tts.example.com/v1/speak?message_id=msg_123&sample_rate=16000&voice=narrator-1
```

## Request rules

`speak.request_rules` is an ordered JSON array. Each rule has a `when` block and a `send` block.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "text": { "$path": "packet.text" },
        "message_id": { "$path": "packet.message_id" }
      }
    }
  }
]
```

| Field         | Required | Description                                                                                 |
| ------------- | -------- | ------------------------------------------------------------------------------------------- |
| `when.packet` | Yes      | Rapida packet that triggers the rule. Supported values are `text`, `done`, and `interrupt`. |
| `send.frame`  | Yes      | Outbound provider message type. Supported values are `binary`, `json`, and `text`.          |
| `send.body`   | Yes      | Static value or DSL expression tree used as the outbound body.                              |

### Request packet reference

| Packet      | When Rapida sends it                            | Common use                                                                         |
| ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
| `text`      | Assistant text is ready for synthesis.          | Send text, voice, model, and audio options to the provider.                        |
| `done`      | The assistant response text stream is complete. | Send a provider flush, finalization, or end-of-input message.                      |
| `interrupt` | User interruption is detected.                  | Send a provider cancel, clear, or stop message before Rapida closes the WebSocket. |

### Request frame reference

| `send.frame` | `send.body` must resolve to | Use when                                                                                     |
| ------------ | --------------------------- | -------------------------------------------------------------------------------------------- |
| `binary`     | Bytes or string             | The provider expects a binary control or payload frame. This is uncommon for TTS text input. |
| `json`       | Valid JSON value            | The provider expects structured text, voice, model, or control messages.                     |
| `text`       | Value convertible to string | The provider expects raw text WebSocket messages.                                            |

Every matching request rule for a packet is sent in order. This lets one `text`, `done`, or `interrupt` packet produce more than one provider message when required.

### Request scope

Request rules use `$path` to read from the request scope.

For `text`:

```json theme={null}
{
  "config": {
    "voice": {
      "id": "voice_123"
    },
    "model": "sonic-2",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "text",
    "message_id": "msg_123",
    "text": "Hello world"
  }
}
```

For `done` and `interrupt`, `packet.text` is present but may be empty:

```json theme={null}
{
  "config": {
    "voice": {
      "id": "voice_123"
    },
    "model": "sonic-2",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "done",
    "message_id": "msg_123",
    "text": ""
  }
}
```

### Request path reference

| Path                       | Available on | Description                                                                                       |
| -------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| `config.voice.id`          | All packets  | Optional provider voice from `speak.voice.id`. Empty when not configured.                         |
| `config.model`             | All packets  | Optional provider model from `speak.model`. Empty when not configured.                            |
| `config.language`          | All packets  | Optional provider language from `speak.language`. Empty when not configured.                      |
| `config.audio.encoding`    | All packets  | Audio encoding expected from provider responses.                                                  |
| `config.audio.sample_rate` | All packets  | Audio sample rate expected from provider responses.                                               |
| `packet.kind`              | All packets  | Current packet type.                                                                              |
| `packet.message_id`        | All packets  | Current synthesis message or context ID.                                                          |
| `packet.text`              | All packets  | Assistant text for `text` packets. Empty or provider-specific for `done` and `interrupt` packets. |

### One-shot synthesis example

Use this when the provider synthesizes each text packet immediately.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "text": { "$path": "packet.text" },
        "voice_id": "narrator-1",
        "message_id": { "$path": "packet.message_id" },
        "model": "sonic-2",
        "language": "en-US",
        "audio": {
          "encoding": { "$path": "config.audio.encoding" },
          "sample_rate": {
            "$cast": "number",
            "value": { "$path": "config.audio.sample_rate" }
          }
        }
      }
    }
  }
]
```

### Text, done, and interrupt example

Use this when the provider expects text payloads, an explicit final message, and an explicit cancel message.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "type": "speak",
        "text": { "$path": "packet.text" },
        "voice": "narrator-1",
        "request_id": { "$path": "packet.message_id" },
        "audio": {
          "encoding": { "$path": "config.audio.encoding" },
          "sample_rate": {
            "$cast": "number",
            "value": { "$path": "config.audio.sample_rate" }
          }
        }
      }
    }
  },
  {
    "when": { "packet": "done" },
    "send": {
      "frame": "json",
      "body": {
        "type": "done",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": {
        "type": "interrupt",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  }
]
```

<Warning>
  Add an `interrupt` rule if your provider needs an explicit cancel or clear message. Rapida sends the matching `interrupt` request first, then closes the WebSocket connection.
</Warning>

## Response rules

`speak.response_rules` is an ordered JSON array. Each provider WebSocket response is parsed into a `binary`, `json`, or `text` frame, then the first matching response rule is evaluated. Custom TTS response rules support `binary` and `json`; text responses are ignored unless you change the provider to send JSON status messages.

```json theme={null}
[
  {
    "when": { "frame": "binary" },
    "emit": {
      "audio": { "$frame": "binary" }
    }
  }
]
```

| Field         | Required | Description                                                                                              |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `when.frame`  | Yes      | Provider response frame type. Supported values are `binary` and `json`.                                  |
| `when.path`   | No       | Dot path inside a JSON response frame. Must be paired with `when.equals`. Not allowed for binary frames. |
| `when.equals` | No       | Primitive value compared against `when.path` for JSON frames.                                            |
| `emit`        | Yes      | Object that tells Rapida what to emit. Supported keys are `audio`, `message_id`, `done`, and `error`.    |

### Response frame parsing

| Provider response                                | Parsed as | Notes                                                         |
| ------------------------------------------------ | --------- | ------------------------------------------------------------- |
| WebSocket binary message                         | `binary`  | Use `{ "$frame": "binary" }` to emit the full frame as audio. |
| WebSocket text message containing one JSON value | `json`    | Use `$path` to read fields from JSON objects.                 |
| WebSocket text message that is not valid JSON    | `text`    | Custom TTS response rules do not support text frames.         |

### Response matching

| Rule shape                                               | Match behavior                                       |
| -------------------------------------------------------- | ---------------------------------------------------- |
| `{ "frame": "binary" }`                                  | Matches any binary frame.                            |
| `{ "frame": "json" }`                                    | Matches any JSON response.                           |
| `{ "frame": "json", "path": "type", "equals": "chunk" }` | Matches a JSON response where `type` equals `chunk`. |

For JSON rules, `when.path` and `when.equals` must be provided together. `when.equals` must be a primitive JSON value: string, number, boolean, or null.

For binary rules, `when.path` and `when.equals` are not allowed.

### Emit keys

| Emit key     | Required | Type after evaluation | Effect                                                                                              |
| ------------ | -------- | --------------------- | --------------------------------------------------------------------------------------------------- |
| `audio`      | No       | bytes or string       | Emits a TTS audio chunk. Use bytes for raw audio or `$decode` for base64 audio in JSON.             |
| `message_id` | No       | string                | Associates audio, error, or done with a message. Falls back to the current context ID when omitted. |
| `done`       | No       | boolean               | When `true`, ends synthesis for the message, closes the connection, and emits a TTS end packet.     |
| `error`      | No       | string                | Emits a TTS error when the value is non-empty.                                                      |

<Warning>
  If a response rule emits `error`, Rapida emits a TTS error. If a response emits `done: true`, Rapida closes the provider connection. If a rule emits neither `audio`, non-empty `error`, nor `done: true`, the response is ignored.
</Warning>

### Binary audio response example

Use this when the provider streams raw audio as binary WebSocket frames.

```json theme={null}
[
  {
    "when": { "frame": "binary" },
    "emit": {
      "audio": { "$frame": "binary" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "done": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "error": { "$path": "error.message" },
      "done": true
    }
  }
]
```

### JSON base64 audio response example

Use `$decode` when the provider returns base64-encoded audio inside JSON.

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "chunk" },
    "emit": {
      "audio": {
        "$decode": "base64",
        "value": { "$path": "audio" }
      },
      "message_id": { "$path": "message_id" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "done": true
    }
  }
]
```

## DSL operators

Every DSL operator is a JSON object with one operator key. Operator objects must contain only the operator and its required fields.

### `$var`

Reads a supported query variable inside `speak.query_params`.

```json theme={null}
{ "$var": "voice_id" }
```

| Supported in          | Supported values                                                         |
| --------------------- | ------------------------------------------------------------------------ |
| Query parameters only | `message_id`, `voice_id`, `model`, `language`, `encoding`, `sample_rate` |

Rules:

* `$var` must be a non-empty string.
* The operator object must contain only `$var`.
* `$var` is not supported in request rules or response rules. Use `$path` there.
* `text` is not supported as a query variable.

### `$path`

Reads a dot-separated path from the current request scope or JSON response frame.

```json theme={null}
{ "$path": "packet.text" }
```

```json theme={null}
{ "$path": "chunks.0.audio" }
```

| Supported in   | Path source                          |
| -------------- | ------------------------------------ |
| Request rules  | `config` and `packet` request scope. |
| Response rules | Current JSON response object.        |

Rules:

* `$path` must be a non-empty string.
* The operator object must contain only `$path`.
* Dot-separated object keys are traversed by key.
* Arrays are traversed by numeric index, such as `chunks.0.audio`.
* Keys that contain a literal dot are not addressable.
* Missing paths in `when.path` cause the rule not to match.
* Missing paths in `send.body` or `emit` cause an error.
* Response rules can use `$path` only when the current frame is `json`.

### `$cast`

Casts a rendered value to another type.

```json theme={null}
{
  "$cast": "number",
  "value": { "$path": "config.audio.sample_rate" }
}
```

| Supported in                                    | Supported casts               |
| ----------------------------------------------- | ----------------------------- |
| Query parameters, request rules, response rules | `string`, `number`, `boolean` |

Rules:

* `$cast` must be `string`, `number`, or `boolean`.
* The operator object must contain only `$cast` and `value`.
* `value` can be a literal or another DSL expression.

Cast behavior:

| Cast      | Behavior                                                                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`  | Converts strings, bytes, numbers, booleans, and null to string form.                                                                                              |
| `number`  | Converts JSON numbers, numeric values, and numeric strings to an integer or float.                                                                                |
| `boolean` | Converts booleans, boolean strings, and numeric values. JSON numbers are accepted as `0` or `1`; typed numeric values use zero as `false` and non-zero as `true`. |

### `$frame`

Reads the full current binary response frame.

```json theme={null}
{ "$frame": "binary" }
```

| Supported in        | Supported selector |
| ------------------- | ------------------ |
| Response rules only | `binary`           |

Rules:

* `$frame` must be `binary`.
* The operator object must contain only `$frame`.
* `$frame` is useful when the provider streams raw audio as binary WebSocket frames.
* `$frame: "text"` and `$frame: "json"` are not supported for Custom TTS.

### `$decode`

Decodes a base64 string into bytes.

```json theme={null}
{
  "$decode": "base64",
  "value": { "$path": "audio" }
}
```

| Supported in        | Supported format |
| ------------------- | ---------------- |
| Response rules only | `base64`         |

Rules:

* `$decode` must be `base64`.
* The operator object must contain only `$decode` and `value`.
* `value` must resolve to a base64 string.
* Use `$decode` when a JSON response contains base64 audio that should become a playable audio chunk.

### Unsupported operators and expressions

The following are not supported in Custom TTS:

* `$frame: "text"`
* `$frame: "json"`
* `$decode` formats other than `base64`
* Text response frames
* Regex, contains, starts-with, greater-than, less-than, and compound conditions
* String interpolation or concatenation
* Fallback values inside expressions
* Dynamic headers
* Dynamic URL path segments
* Environment variable reads
* JavaScript or function calls

## Complete setup example

Credential:

```json theme={null}
{
  "apiCompatibility": "websocket_v1",
  "baseUrl": "wss://tts.example.com/v1/speak",
  "headers": {
    "Authorization": "Bearer sk_example"
  }
}
```

Audio settings:

```json theme={null}
{
  "speak.audio.encoding": "LINEAR16",
  "speak.audio.sample_rate": "16000"
}
```

Query parameters:

```json theme={null}
{
  "voice": "narrator-1",
  "message_id": { "$var": "message_id" }
}
```

Request rules:

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "type": "speak",
        "text": { "$path": "packet.text" },
        "voice": "narrator-1",
        "request_id": { "$path": "packet.message_id" },
        "audio": {
          "encoding": { "$path": "config.audio.encoding" },
          "sample_rate": {
            "$cast": "number",
            "value": { "$path": "config.audio.sample_rate" }
          }
        }
      }
    }
  },
  {
    "when": { "packet": "done" },
    "send": {
      "frame": "json",
      "body": {
        "type": "done",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": {
        "type": "interrupt",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  }
]
```

Response rules:

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "chunk" },
    "emit": {
      "audio": {
        "$decode": "base64",
        "value": { "$path": "audio" }
      },
      "message_id": { "$path": "request_id" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "request_id" },
      "done": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "message_id": { "$path": "request_id" },
      "error": { "$path": "error.message" },
      "done": true
    }
  }
]
```

## Runtime behavior

* Rapida builds the final WebSocket URL from `baseUrl` and `speak.query_params`.
* Rapida sends static `headers` from the credential during the WebSocket handshake.
* Rapida opens a connection per active message or context. A new context closes the previous connection.
* `text` packets open the WebSocket connection if needed.
* `done` and `interrupt` request rules are optional. If no rule exists for that packet, nothing is sent.
* On interruption, Rapida sends the optional `interrupt` rule first, then closes the WebSocket connection.
* Provider audio is interpreted as `speak.audio.encoding` and `speak.audio.sample_rate`, then resampled internally when needed.
* If no response rule matches a provider response, the response is ignored.
* If a response emits non-empty `error`, Rapida emits a TTS error.
* If a response emits audio, Rapida emits a TTS audio packet.
* If a response emits `done: true`, Rapida closes the connection and emits a TTS end packet.
* If the provider closes the WebSocket normally after synthesis has started, Rapida treats that as completion.

## Validation checklist

Before saving or testing, confirm the following:

* `apiCompatibility` is `websocket_v1` or omitted.
* `baseUrl` is present and points to the correct WebSocket endpoint.
* `headers` include required provider authentication.
* `speak.audio.encoding` matches the provider response audio.
* `speak.audio.sample_rate` matches the provider response audio.
* `speak.request_rules` is valid JSON and contains at least one `text` rule.
* `speak.response_rules` is valid JSON and contains at least one matching audio, done, or error rule.
* Binary audio providers use `{ "$frame": "binary" }`.
* JSON base64 audio providers use `{ "$decode": "base64", "value": ... }`.
* Providers that require finalization have a `done` request rule.
* Providers that require cancellation have an `interrupt` request rule.

## Troubleshooting

| Symptom                                        | Likely cause                                                        | What to check                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| WebSocket does not connect                     | Incorrect URL, unsupported compatibility, or authentication failure | Confirm `apiCompatibility`, `baseUrl`, and `headers`.                                                                              |
| Provider receives no text                      | Missing or non-matching `text` request rule                         | Add a rule with `when.packet: "text"`.                                                                                             |
| Provider receives JSON but expected plain text | Wrong request frame                                                 | Use `send.frame: "text"` with `{ "$path": "packet.text" }`.                                                                        |
| Audio never plays                              | Response rule does not emit audio                                   | Check `when.frame`, `when.path`, `$frame`, `$decode`, and the actual provider response shape.                                      |
| Audio sounds distorted                         | Encoding or sample rate mismatch                                    | Confirm `speak.audio.encoding` and `speak.audio.sample_rate` match the provider audio.                                             |
| Audio keeps playing after interruption         | Missing provider cancel message                                     | Add an `interrupt` request rule that sends the provider's cancel or clear message.                                                 |
| Session never ends cleanly                     | Missing done handling                                               | Emit `done: true` from the provider's done frame, or rely only on normal WebSocket close if your provider closes after completion. |
| Base64 audio fails                             | Wrong `$decode` source                                              | Confirm the `$path` points to a base64 string and not a nested object.                                                             |

## Related

<CardGroup>
  <Card title="Text-to-Speech" icon="volume-2" href="/assistants/text-to-speech">
    Configure standard TTS providers and speech delivery.
  </Card>

  <Card title="Speak configuration" icon="volume-2" href="/assistants/configuration/speak">
    See how TTS fits into assistant voice output settings.
  </Card>

  <Card title="Custom STT" icon="mic" href="/integrations/stt/custom">
    Configure a custom speech-to-text provider with the related DSL pattern.
  </Card>

  <Card title="Assistant API Custom TTS" icon="code" href="/opensource/services/assistant-api/tts/custom">
    Review runtime behavior for self-hosted assistant-api deployments.
  </Card>
</CardGroup>


# Deepgram Text-to-Speech
Source: https://doc.rapida.ai/integrations/tts/deepgram

Deepgram's text-to-speech service provides ultra-realistic voice synthesis with natural-sounding output.

## Getting Started

To integrate Deepgram Text-to-Speech with your Rapida application, follow these steps:

## Supported Models

### Text-to-Speech Models

| Model Name      | Quality  | Use Case                                    |
| --------------- | -------- | ------------------------------------------- |
| aura-asteria-en | Premium  | Ultra-realistic voices, high-quality output |
| aura-luna-en    | Premium  | Natural, expressive female voices           |
| aura-stella-en  | Premium  | Professional male voices                    |
| aura-juniper-en | Standard | Cost-effective, quality voices              |

### Supported Languages

Deepgram TTS supports 20+ languages including:

* English (US, UK, Australian, Indian variants)
* Spanish, French, German, Italian, Dutch
* Portuguese, Russian, German, Polish
* Japanese, Mandarin, Korean
* And more

### Voice Characteristics

Each Deepgram voice model includes:

* **Multiple Voices**: Different voice personalities
* **Emotion Styles**: Express different emotions and tones
* **Pronunciation Control**: Fine-tune how words are pronounced
* **Speed Control**: Adjust speaking rate

## Prerequisites

* Have a Deepgram account (sign up at [https://deepgram.com](https://deepgram.com))
* Navigate to your API dashboard
* Generate an API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Deepgram">
    On the Integrations page, find the Deepgram provider card.

    Click the "Setup Credential" button for Deepgram.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Deepgram" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Deepgram API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Deepgram provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Deepgram Text-to-Speech provider credential is now set up.

## Integration Features

* **Ultra-Realistic Voices**: Industry-leading voice quality
* **20+ Languages**: Comprehensive global language support
* **Multiple Voice Options**: Choose from various voice personalities
* **Emotion Control**: Express different emotional tones
* **Real-time Streaming**: Stream audio in real-time
* **Low Latency**: Fast response times for interactive applications
* **Pronunciation Control**: Fine-tune specific word pronunciations

For more information, visit the [Deepgram TTS documentation](https://developers.deepgram.com/docs).


# ElevenLabs
Source: https://doc.rapida.ai/integrations/tts/elevenlabs

ElevenLabs provides state-of-the-art text-to-speech with natural-sounding AI voices and advanced voice customization.

## Getting Started

To integrate ElevenLabs with your Rapida application for text-to-speech (TTS) capabilities, follow these steps:

## Supported Models

### Text-to-Speech Models

| Model Name          | Features               | Best For                                     |
| ------------------- | ---------------------- | -------------------------------------------- |
| Eleven Monolingual  | Standard quality       | Monolingual content in various languages     |
| Eleven Multilingual | Cross-language support | Code-switching and multilingual content      |
| Turbo V2.5          | Fast processing        | Real-time applications requiring low latency |
| Turbo               | Latest turbo model     | Balanced quality and speed                   |

### Supported Languages

ElevenLabs supports 29+ languages including:

* English (US, UK, Australian, Indian, South African variants)
* Spanish, French, German, Italian, Dutch
* Portuguese (Brazilian & European), Russian, Polish
* Japanese, Mandarin, Korean, Vietnamese
* Hindi, Bengali, Arabic, Hebrew, Turkish
* Greek, Romanian, Swedish, Danish, Finnish, and more

### Voice Library

ElevenLabs provides:

* **Pre-made Voices**: 500+ professional voices
* **Voice Creator**: Create custom AI voices
* **Voice Cloning**: Clone existing voices (with consent)
* **Voice Design**: Design custom voices with specific characteristics

## Prerequisites

* Have an ElevenLabs account (sign up at [https://elevenlabs.io](https://elevenlabs.io))
* Navigate to your account settings
* Go to the API Keys section
* Generate a new API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select ElevenLabs">
    On the Integrations page, find the ElevenLabs provider card.

    Click the "Setup Credential" button for ElevenLabs.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "ElevenLabs" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your ElevenLabs API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The ElevenLabs provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your ElevenLabs provider credential is now set up for text-to-speech integration.

## Integration Features

* **Natural-Sounding Voices**: 500+ professional AI voices
* **29+ Languages**: Extensive global language support
* **Custom Voice Creation**: Create unique brand voices
* **Voice Cloning**: Clone and customize existing voices
* **Real-time Streaming**: Stream audio as it's generated
* **Pronunciation Adjustment**: Fine-tune pronunciation for specific words
* **Emotional Expression**: Control emotional tone of speech
* **Voice Design**: Advanced tools for voice customization

## Voice Characteristics

You can fine-tune:

* **Stability**: How consistent the voice is
* **Clarity**: Voice clarity and precision
* **Accent**: Regional accent and pronunciation
* **Age**: Perceived age of the speaker
* **Tone**: Emotional tone and personality

For more information, visit the [ElevenLabs documentation](https://docs.elevenlabs.io/).


# Google Text-to-Speech
Source: https://doc.rapida.ai/integrations/tts/google-speech-service

Google Cloud Text-to-Speech provides natural-sounding voice synthesis powered by advanced neural networks.

## Getting Started

To integrate Google Cloud Text-to-Speech with your Rapida application for text-to-speech (TTS) capabilities, follow these steps:

## Supported Models

### Text-to-Speech Voices

Google Cloud provides neural voices with natural, expressive speech synthesis:

#### English Voices

| Voice Name      | Gender | Regional Accent | Description                   |
| --------------- | ------ | --------------- | ----------------------------- |
| en-US-Neural2-A | Female | US              | Natural US English female     |
| en-US-Neural2-C | Female | US              | Alternative US English female |
| en-US-Neural2-E | Male   | US              | Natural US English male       |
| en-GB-Neural2-A | Female | UK              | British English female        |
| en-GB-Neural2-B | Male   | UK              | British English male          |
| en-AU-Neural2-A | Female | Australian      | Australian English female     |
| en-AU-Neural2-B | Male   | Australian      | Australian English male       |
| en-IN-Neural2-A | Female | Indian          | Indian English female         |
| en-IN-Neural2-B | Male   | Indian          | Indian English male           |

### Supported Languages

Google Cloud Text-to-Speech supports 30+ languages including:

* English (US, UK, Australian, Indian, South African variants)
* Spanish, French, German, Italian, Dutch
* Mandarin, Cantonese, Japanese, Korean
* Hindi, Bengali, Tamil, Telugu, Marathi
* Portuguese, Russian, Arabic, Polish, Turkish
* Thai, Vietnamese, Filipino, and more

### Features

* **Neural Voices**: Advanced neural network-based voice synthesis
* **Multiple Accents**: Native speaker accents for various regions
* **Speaking Rate**: Adjust speech speed from 0.25x to 4.0x
* **Pitch Control**: Fine-tune voice pitch
* **Audio Formats**: Multiple audio formats and sample rates
* **SSML Support**: Full SSML markup support

## Prerequisites

* Have a Google Cloud account
* Create a new Google Cloud Project or use an existing one
* Enable the Text-to-Speech API
* Create a service account with Text-to-Speech permissions
* Download the service account key (JSON file)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Google Speech Service">
    On the Integrations page, find the Google Speech Service provider card.

    Click the "Setup Credential" button for Google Speech Service (for TTS).
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Google Speech Service" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter Project ID: Input your Google Cloud Project ID
    4. Enter Service Account Key: Paste the entire JSON content of your service account key
    5. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Google Speech Service provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Google Cloud Text-to-Speech provider credential is now set up for TTS integration.

## Integration Features

* **Natural Neural Voices**: High-quality neural voice synthesis
* **30+ Languages**: Comprehensive language support
* **Multiple Accents**: Native speaker accents for various regions
* **SSML Support**: Advanced markup for precise voice control
* **Real-time Streaming**: Stream audio as it's being synthesized
* **Batch Processing**: Process large volumes of text
* **Affordable**: Cost-effective pay-as-you-go pricing

For more information, visit the [Google Cloud Text-to-Speech documentation](https://cloud.google.com/text-to-speech/docs).


# Groq TTS
Source: https://doc.rapida.ai/integrations/tts/groq

Groq provides ultra-fast text-to-speech via an OpenAI-compatible API powered by its LPU inference engine.

## Overview

Groq delivers text-to-speech through its OpenAI-compatible HTTP API, accelerated by the LPU inference engine for extremely low-latency synthesis. It supports English and Arabic voices through the PlayAI voice collection.

## Authentication

| Key   | Description                                               |
| ----- | --------------------------------------------------------- |
| `key` | API key from [console.groq.com](https://console.groq.com) |

## Configuration

| Option     | Description                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| `model`    | Model: `playai-tts` (English), `playai-tts-arabic` (Arabic)                               |
| `voice_id` | PlayAI voice name (e.g. `Arista-PlayAI`, `Atlas-PlayAI`, `Celeste-PlayAI`, `Chip-PlayAI`) |

## Getting Started

<Steps>
  <Step title="Add Groq credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Groq API key from your [Groq console](https://console.groq.com).
  </Step>

  <Step title="Select Groq as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **Groq** as your Text-to-Speech provider.
  </Step>

  <Step title="Choose a model and voice">
    Select `playai-tts` for English or `playai-tts-arabic` for Arabic, then specify a PlayAI voice ID.
  </Step>
</Steps>

## Related

* [Groq STT](/integrations/stt/groq)
* [OpenAI TTS](/integrations/tts/openai-tts)


# MiniMax
Source: https://doc.rapida.ai/integrations/tts/minimax

MiniMax provides high-quality speech synthesis via HTTP streaming SSE with multiple model tiers.

## Overview

MiniMax is a speech synthesis platform that delivers streaming TTS via Server-Sent Events (SSE). It offers multiple model tiers — from fast turbo options to high-definition output — suitable for both low-latency and quality-focused voice assistants.

## Authentication

| Key        | Description                                   |
| ---------- | --------------------------------------------- |
| `key`      | API key from [minimax.io](https://minimax.io) |
| `group_id` | Group ID associated with your MiniMax account |

## Configuration

| Option     | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `model`    | Model tier: `speech-02-turbo`, `speech-02-hd`, `speech-2.6-turbo`, `speech-2.6-hd` |
| `voice_id` | MiniMax voice identifier (system or custom voice)                                  |

## Getting Started

<Steps>
  <Step title="Add MiniMax credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your MiniMax API key and Group ID from your [MiniMax account](https://minimax.io).
  </Step>

  <Step title="Select MiniMax as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **MiniMax** as your Text-to-Speech provider.
  </Step>

  <Step title="Choose a model and voice">
    Select a model tier based on your latency and quality requirements, then specify a voice ID.
  </Step>
</Steps>

## Related

* [ElevenLabs TTS](/integrations/tts/elevenlabs)
* [Deepgram TTS](/integrations/tts/deepgram)


# Neuphonic
Source: https://doc.rapida.ai/integrations/tts/neuphonic

Neuphonic provides multilingual streaming text-to-speech via WebSocket with adjustable speech speed.

## Overview

Neuphonic is a text-to-speech platform offering real-time voice synthesis via WebSocket streaming. It supports a wide range of languages and provides speed control for flexible voice assistant deployments.

## Authentication

| Key   | Description                                         |
| ----- | --------------------------------------------------- |
| `key` | API key from [neuphonic.com](https://neuphonic.com) |

## Configuration

| Option     | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `voice_id` | Neuphonic voice identifier                                          |
| `language` | Language code (e.g. `en`, `de`, `es`, `fr`, `pt`, `it`, `nl`, `pl`) |
| `speed`    | Speech speed multiplier (0.1–3.0; default `1.0`)                    |

## Getting Started

<Steps>
  <Step title="Add Neuphonic credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Neuphonic API key from your [Neuphonic account](https://neuphonic.com).
  </Step>

  <Step title="Select Neuphonic as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **Neuphonic** as your Text-to-Speech provider.
  </Step>

  <Step title="Configure voice and language">
    Select a voice ID and set the desired language code. Adjust the speed parameter if needed.
  </Step>
</Steps>

## Related

* [Rime TTS](/integrations/tts/rime)
* [ElevenLabs TTS](/integrations/tts/elevenlabs)


# NVIDIA TTS
Source: https://doc.rapida.ai/integrations/tts/nvidia

NVIDIA provides enterprise-grade neural text-to-speech via the NVCF API.

## Overview

NVIDIA delivers text-to-speech through the NVIDIA Cloud Functions (NVCF) API, serving neural voice synthesis from NVIDIA's high-throughput inference infrastructure. It is well-suited for enterprise deployments requiring scalable, low-latency TTS.

## Authentication

| Key           | Description                                               |
| ------------- | --------------------------------------------------------- |
| `key`         | API key from [build.nvidia.com](https://build.nvidia.com) |
| `function_id` | NVCF Function ID for the TTS model endpoint               |

## Configuration

| Option     | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| `voice_id` | NVIDIA voice identifier (e.g. `English-US.Female-1`, `English-US.Male-1`) |
| `language` | Language code (e.g. `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`)          |

## Getting Started

<Steps>
  <Step title="Add NVIDIA credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your NVIDIA API key and the NVCF Function ID for the desired TTS model from [build.nvidia.com](https://build.nvidia.com).
  </Step>

  <Step title="Select NVIDIA as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **NVIDIA** as your Text-to-Speech provider.
  </Step>

  <Step title="Configure voice and language">
    Specify the voice ID and language code matching your deployment requirements.
  </Step>
</Steps>

## Related

* [NVIDIA STT](/integrations/stt/nvidia)
* [Azure Speech TTS](/integrations/tts/azure-speech-service)


# OpenAI TTS
Source: https://doc.rapida.ai/integrations/tts/openai-tts

OpenAI Text-to-Speech delivers natural-sounding speech synthesis with multiple high-quality voices.

OpenAI TTS produces natural, expressive speech from text using neural voice synthesis. It supports multiple distinct voices and is available in standard and HD quality tiers.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add OpenAI credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard and add your OpenAI API key. This credential is shared across all OpenAI services (LLM, Whisper STT, and TTS).
  </Step>

  <Step title="Select OpenAI as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **OpenAI** as your Text-to-Speech provider.
  </Step>

  <Step title="Choose a voice">
    Select from the available voices to match your assistant's persona.
  </Step>
</Steps>

## Available Voices

| Voice     | Character             |
| --------- | --------------------- |
| `alloy`   | Neutral, balanced     |
| `echo`    | Male, clear           |
| `fable`   | Expressive, narrative |
| `onyx`    | Deep, authoritative   |
| `nova`    | Warm, natural         |
| `shimmer` | Clear, bright         |

## Supported Models

| Model      | Description                                           |
| ---------- | ----------------------------------------------------- |
| `tts-1`    | Optimized for real-time, low-latency synthesis        |
| `tts-1-hd` | Higher quality, best for offline or non-real-time use |

For real-time voice assistants, use `tts-1` to minimize latency.

## Configuration Options

| Option | Description                                               | Default |
| ------ | --------------------------------------------------------- | ------- |
| Model  | `tts-1` or `tts-1-hd`                                     | `tts-1` |
| Voice  | One of the six voices above                               | `alloy` |
| Speed  | Playback speed multiplier (0.25–4.0)                      | `1.0`   |
| Format | Output format: `mp3`, `opus`, `aac`, `flac`, `wav`, `pcm` | `pcm`   |

## Notes

* Use `tts-1` for real-time conversations; `tts-1-hd` adds perceptible latency.
* Audio is streamed in chunks, so playback begins before synthesis is fully complete.
* Pricing is per 1,000 characters of input text. See [OpenAI TTS pricing](https://openai.com/pricing).

## Related

* [OpenAI Whisper STT](/integrations/stt/openai-whisper)
* [OpenAI LLM](/integrations/llm/openai)
* [ElevenLabs TTS](/integrations/tts/elevenlabs)


# Resemble AI
Source: https://doc.rapida.ai/integrations/tts/resemble

Resemble AI provides high-quality, real-time voice synthesis with support for custom voice cloning.

Resemble AI specializes in neural text-to-speech and voice cloning. It is particularly well-suited for branded voice assistants where a custom or cloned voice is needed to match a specific persona or brand identity.

## Getting Started

Follow these steps to configure your provider:

<Steps>
  <Step title="Add Resemble AI credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Resemble AI API key from your [Resemble AI account](https://app.resemble.ai).
  </Step>

  <Step title="Select Resemble as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **Resemble** as your Text-to-Speech provider.
  </Step>

  <Step title="Configure your voice UUID">
    Specify the UUID of the voice you want to use. You can use a pre-built Resemble voice or a custom cloned voice from your Resemble account.
  </Step>
</Steps>

## Key Features

* **Voice cloning**: Create a custom voice from a small amount of sample audio
* **Real-time synthesis**: Low-latency streaming for live voice assistant applications
* **Emotion control**: Adjust speech emotion and style programmatically
* **SSML support**: Fine-grained control over pronunciation, pauses, and emphasis
* **Localization**: Multilingual synthesis with the same cloned voice

## Configuration Options

| Option       | Description                                           |
| ------------ | ----------------------------------------------------- |
| API key      | Resemble AI authentication key                        |
| Voice UUID   | UUID of the target voice (from your Resemble account) |
| Project UUID | UUID of the Resemble project containing your voice    |
| Sample rate  | Output audio sample rate                              |

## Notes

* Voice cloning requires a minimum of 30–60 minutes of clean audio recordings per voice.
* Real-time streaming latency is typically under 300ms for the first audio chunk.
* Resemble charges per character synthesized plus a monthly fee for custom voices. See [Resemble pricing](https://www.resemble.ai/pricing/).

## Related

* [ElevenLabs TTS](/integrations/tts/elevenlabs)
* [Deepgram TTS](/integrations/tts/deepgram)


# Rime
Source: https://doc.rapida.ai/integrations/tts/rime

Rime offers ultra-low-latency text-to-speech with natural-sounding voices via WebSocket streaming.

## Getting Started

To integrate Rime with your Rapida application for text-to-speech (TTS) capabilities, follow these steps:

## Supported Models

### Text-to-Speech Models

| Model Name | Model ID | Best For                           |
| ---------- | -------- | ---------------------------------- |
| Mist       | `mist`   | Fast, lightweight speech synthesis |
| Mist v2    | `mistv2` | Improved quality with low latency  |
| Arcana     | `arcana` | Highest quality flagship voices    |

### Supported Languages

Rime supports the following languages:

* English (`eng`)
* Spanish (`spa`)
* Hindi (`hin`)
* French (`fra`)
* German (`ger`)

### Voice Library

Rime provides two voice families:

* **Arcana Voices**: Premium flagship voices — Luna, Celeste, Orion, Ursa, Astra, Esther, Estelle, Andromeda
* **Mist Voices**: Fast low-latency voices — River, Cove, Peak, Colby, Tibur, Ana, Vespera
* **Custom Voices**: You can also use custom voice IDs created through the Rime platform

## Prerequisites

* Have a Rime account (sign up at [https://rime.ai](https://rime.ai))
* Navigate to your account dashboard
* Generate a new API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Rime">
    On the Integrations page, find the Rime provider card.

    Click the "Setup Credential" button for Rime.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Rime" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Rime API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Rime provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Rime provider credential is now set up for text-to-speech integration.

## Integration Features

* **Ultra-Low Latency**: WebSocket streaming for real-time voice synthesis
* **Multiple Model Tiers**: Choose between Mist (fast) and Arcana (premium quality)
* **Multilingual Support**: 5 languages with natural pronunciation
* **Speed Control**: Adjustable speech speed via the speed alpha parameter
* **Custom Pauses**: Insert custom pauses using `<ms>` syntax (e.g., `<500>` for 500ms)
* **PCM Audio Output**: Direct PCM streaming at 16kHz for seamless pipeline integration

## Configuration Options

| Option      | Key                 | Description                                    |
| ----------- | ------------------- | ---------------------------------------------- |
| Model       | `speak.model`       | TTS model: `mist`, `mistv2`, or `arcana`       |
| Voice       | `speak.voice.id`    | Voice identifier (e.g., `river`, `luna`)       |
| Language    | `speak.language`    | Language code (e.g., `eng`, `spa`)             |
| Speed Alpha | `speak.speed_alpha` | Speech speed multiplier (0.1–3.0, default 1.0) |

For more information, visit the [Rime documentation](https://rime.ai/docs).


# Sarvam AI Text-to-Speech
Source: https://doc.rapida.ai/integrations/tts/sarvam

Sarvam AI provides text-to-speech capabilities with strong support for Indian languages.

## Getting Started

To integrate Sarvam AI Text-to-Speech with your Rapida application, follow these steps:

## Supported Models

### Text-to-Speech Models

| Model Name    | Language  | Description                       |
| ------------- | --------- | --------------------------------- |
| sarvam-tts-en | English   | Natural English voice synthesis   |
| sarvam-tts-hi | Hindi     | Natural Hindi voice synthesis     |
| sarvam-tts-ml | Malayalam | Natural Malayalam voice synthesis |
| sarvam-tts-kn | Kannada   | Natural Kannada voice synthesis   |
| sarvam-tts-ta | Tamil     | Natural Tamil voice synthesis     |
| sarvam-tts-te | Telugu    | Natural Telugu voice synthesis    |

### Supported Languages

Sarvam AI specializes in Indian languages:

* **English**: Full support with natural-sounding voices
* **Hindi**: Complete voice synthesis support
* **Regional Languages**:
  * Malayalam
  * Kannada
  * Tamil
  * Telugu
  * And more

### Voice Features

* **Multiple Voice Options**: Different voice personalities for each language
* **Natural Sounding**: Optimized for Indian language phonetics
* **Speed Control**: Adjust speaking rate
* **Pitch Control**: Fine-tune voice pitch
* **Emotion Styles**: Express different emotional tones

## Prerequisites

* Have a Sarvam AI account (sign up at [https://www.sarvam.ai](https://www.sarvam.ai))
* Navigate to your API dashboard
* Generate an API key
* Copy the API key (make sure to save it securely)

# Setting Up Provider Credentials

<Steps>
  <Step title="Access the Integrations Page">
    <img alt="Integrations Page" />

    Navigate to the "Integration > Models" page to access TTS providers.
  </Step>

  <Step title="Select Sarvam AI">
    On the Integrations page, find the Sarvam AI provider card.

    Click the "Setup Credential" button for Sarvam AI.
  </Step>

  <Step title="Create Provider Credential">
    A modal window will appear titled "Create provider credential". Follow these steps:

    1. Select "Sarvam AI" from the dropdown (if not already selected)
    2. Enter a Key Name: Assign a unique name to this provider key for easy identification
    3. Enter the API Key: Input your Sarvam AI API key
    4. Click "Configure" to save the credential
  </Step>

  <Step title="Verify Credential Setup">
    After setting up the credential, you can verify it's been added:

    1. The Sarvam AI provider card should now show "Connected"
    2. If you click on the provider, you'll see a "View provider credential" modal
    3. This modal displays the credential name, when it was last updated, and options to delete or close
  </Step>
</Steps>

Your Sarvam AI Text-to-Speech provider credential is now set up.

## Integration Features

* **Indian Languages First**: Best-in-class support for Indian languages
* **Natural Voices**: Optimized voice synthesis for Indian language speakers
* **Multiple Languages**: English and major Indian languages
* **Quality TTS**: High-quality voice synthesis
* **Developer Friendly**: Easy-to-use APIs
* **Low Latency**: Fast response times
* **Cost-Effective**: Affordable pricing for Indian startups

## Use Cases

* Customer service chatbots in Indian languages
* Voice-enabled e-commerce platforms
* Accessibility for Indian language content
* Educational applications
* Entertainment and media applications
* IoT devices and smart home integration

For more information, visit the [Sarvam AI documentation](https://www.sarvam.ai/).


# Speechmatics TTS
Source: https://doc.rapida.ai/integrations/tts/speechmatics

Speechmatics provides multilingual HTTP streaming text-to-speech backed by its speech platform.

## Overview

Speechmatics provides text-to-speech via HTTP streaming, backed by the same platform known for its highly accurate, language-inclusive speech recognition. It is well-suited for multilingual voice assistants where both STT and TTS from a single provider is preferred.

## Authentication

| Key   | Description                                                             |
| ----- | ----------------------------------------------------------------------- |
| `key` | API key from [portal.speechmatics.com](https://portal.speechmatics.com) |

## Configuration

| Option     | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| `voice_id` | Speechmatics voice identifier                                                   |
| `language` | Language code (e.g. `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ja`, `zh`) |

## Getting Started

<Steps>
  <Step title="Add Speechmatics credentials to your vault">
    Navigate to **Integration → Vault** in the Rapida dashboard. Add your Speechmatics API key from your [Speechmatics account](https://portal.speechmatics.com).
  </Step>

  <Step title="Select Speechmatics as your TTS provider">
    When configuring your assistant, open **Audio Settings** and choose **Speechmatics** as your Text-to-Speech provider.
  </Step>

  <Step title="Configure voice and language">
    Select a voice ID and set the desired language code for your deployment.
  </Step>
</Steps>

## Related

* [Speechmatics STT](/integrations/stt/speechmatics)
* [Deepgram TTS](/integrations/tts/deepgram)


# Rapida Voice AI Platform
Source: https://doc.rapida.ai/introduction/overview

The open-source platform for building, deploying, and operating production voice AI systems at scale.

Rapida is an open-source voice AI orchestration platform. It gives you a complete, production-ready stack — speech processing, LLM routing, telephony, knowledge retrieval, and observability — unified under one system so you stop assembling fragile integrations and start shipping voice AI that works. It is especially well-suited to agencies delivering branded deployments for clients and enterprise teams building voice systems with strict control over data, models, and operations.

<Info>
  Rapida runs as a **fully-managed cloud service** or as a **self-hosted deployment** on your own infrastructure. Same codebase, same APIs, same SDKs — your choice of where it runs.
</Info>

## Platform architecture

<img alt="Rapida Platform Architecture" />

## Omnichannel by default

Deploy the same assistant across every channel from a single configuration. No per-channel codebases, no duplicated logic.

<CardGroup>
  <Card title="Phone" icon="phone" href="/voice-deployment-options/phone">
    Inbound and outbound PSTN calls. Native SIP trunking and WebRTC with direct integrations for Twilio, Vonage, Exotel, and Asterisk.
  </Card>

  <Card title="Web Widget" icon="globe" href="/voice-deployment-options/web-widget">
    Embeddable voice widget for any website. One script tag — no separate assistant configuration needed.
  </Card>

  <Card title="Web App" icon="monitor" href="/voice-deployment-options/web-app">
    React SDK for full-featured voice in your own application. Stream audio over WebRTC with real-time transcripts and complete UI control.
  </Card>

  <Card title="WhatsApp" icon="message-circle" href="/voice-deployment-options/whatsapp">
    Conversational AI on WhatsApp Business via the Meta webhook API. Reach billions of users at messaging scale.
  </Card>
</CardGroup>

<Tip>
  Change your prompt, swap a model, or update a knowledge base once — every channel picks it up instantly. No redeployments.
</Tip>

## Carrier-grade telephony

Most voice AI platforms bolt telephony on as an afterthought. Rapida makes it a first-class concern.

<Note>
  Rapida speaks native **SIP (RFC 3261)**, manages **WebRTC** peer connections with full ICE/STUN/TURN, and ships a built-in **AudioSocket server** for Asterisk — all in the same binary, no media gateways required.
</Note>

* **Connect any provider.** Twilio, Vonage, Exotel, Asterisk, or any SIP-compatible carrier. Switching providers never touches your assistant logic — swap at the channel layer without any code changes.
* **Inbound and outbound at scale.** Handle thousands of simultaneous calls while running outbound dialing campaigns in parallel. Launch campaigns programmatically via SDK or REST bulk call API.
* **Live call transfer.** Transfer active calls to a human agent mid-conversation. Rapida sends a SIP REFER in-flight with no audio gap and hands off the full conversation context to the receiving agent.
* **Mix providers across regions.** Route calls to different telephony providers per region for optimal cost, latency, and compliance without rebuilding your assistant.

## The full stack

<CardGroup>
  <Card title="Speech Processing" icon="mic">
    STT and TTS with VAD, noise cancellation, and sub-300ms latency. Mix providers per language or use case — Deepgram, ElevenLabs, Azure, AWS, OpenAI, and more.
  </Card>

  <Card title="LLM Routing & AgentKit" icon="cpu">
    Route to any LLM — OpenAI, Anthropic, Gemini, Mistral, Bedrock. Or bring your own backend with **AgentKit**: plug any LLM server in over gRPC while Rapida manages the audio pipeline.
  </Card>

  <Card title="Knowledge Retrieval" icon="book-open">
    Connect documents, wikis, and databases. Rapida handles chunking, embedding, and semantic search via OpenSearch so your assistant always has the right context at call time.
  </Card>

  <Card title="Tools, Connectors & Observability" icon="layers">
    Call HTTP endpoints mid-conversation, sync data from Notion, GitHub, HubSpot, Jira, and more. Every call is logged with full transcripts, latency breakdowns, and webhook delivery.
  </Card>
</CardGroup>

## Works with everything you use

Rapida is provider-agnostic. Swap any layer without changing your assistant configuration.

| Layer                  | Supported providers                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **LLM**                | OpenAI, Anthropic, Azure OpenAI, Google Gemini, Vertex AI, Mistral, Cohere, AWS Bedrock, HuggingFace, VoyageAI, AgentKit (custom gRPC) |
| **STT**                | Deepgram, AssemblyAI, Azure, Google, AWS Transcribe, OpenAI Whisper, Cartesia, Rev.ai, Speechmatics, Sarvam                            |
| **TTS**                | ElevenLabs, Deepgram, Azure, Google, AWS Polly, OpenAI, Cartesia, Resemble, Sarvam                                                     |
| **VAD**                | Silero, FireRed                                                                                                                        |
| **Noise Cancellation** | RNNoise                                                                                                                                |
| **End of Speech**      | Silence-based, Pipecat turn detector                                                                                                   |
| **Telephony**          | Twilio, Vonage, Exotel, Asterisk (AudioSocket + WebSocket), any SIP trunk                                                              |

## From demo to enterprise scale

Most teams start with a single assistant and a handful of test calls. Rapida is designed so the same codebase, the same APIs, and the same configuration that worked for your demo handles your production traffic — without re-architecting at every order of magnitude.

* **Day one.** One API call, one assistant, one channel. The managed cloud handles infrastructure so you can focus on the product.
* **Team growth.** Add knowledge bases, connect CRM tools, define endpoint tools, roll out to more channels — all from the same platform, no new services to operate.
* **Production scale.** Rapida's Go microservices scale horizontally and independently. Each service — voice orchestration, LLM routing, endpoint invocation, document processing — runs as a stateless unit behind a load balancer. Redis handles distributed state and pub/sub. OpenSearch scales knowledge retrieval across millions of documents.
* **Enterprise deployment.** Private VPC, dedicated infrastructure, custom SLAs, and full data residency. Move from managed cloud to self-hosted without changing a line of your application code.

<Note>
  Rapida has no arbitrary call concurrency limits built into the platform. Throughput scales with infrastructure — horizontal pod autoscaling, Redis cluster, and OpenSearch node expansion are all first-class deployment patterns.
</Note>

## Built for enterprise — technical and legal

Enterprise adoption of voice AI faces two distinct scrutiny layers: the engineering team evaluates correctness, latency, and operability; legal and compliance teams evaluate data handling, sovereignty, and auditability. Rapida is built to satisfy both.

<CardGroup>
  <Card title="Data Sovereignty" icon="lock">
    Self-hosted deployments run entirely on your infrastructure. No audio, no transcripts, no customer data transits Rapida's servers. Deploy in any region — your data stays where regulations require it.
  </Card>

  <Card title="Open Source Auditability" icon="code">
    The full platform is open source. Legal and security teams can audit every component that handles customer data — the audio pipeline, LLM routing layer, credential vault, and logging system — without relying on vendor assurances.
  </Card>

  <Card title="Compliance-aligned deployment" icon="shield">
    Self-hosted deployments on HIPAA-compliant or GDPR-scoped infrastructure with your own BAAs and DPAs. Audit logs for every call, tool invocation, and API access. Configurable data retention and PII redaction at the transcript level.
  </Card>

  <Card title="Governance & Access Control" icon="users">
    Organization → Project RBAC hierarchy. Scoped roles (Super Admin, Admin, Writer, Reader) across all resources. A credential vault stores all API keys and OAuth tokens encrypted at rest — no secrets in environment variables or config files.
  </Card>

  <Card title="No Vendor Lock-in" icon="git-branch">
    Open source with no proprietary formats. Swap LLMs, STT, TTS, or telephony providers at the configuration layer. If Rapida ever stops fitting your needs, your assistant logic, knowledge bases, and integration configs are all yours to take.
  </Card>

  <Card title="Scalable, Observable Architecture" icon="activity">
    Every call emits structured logs, latency spans, and token usage metrics. Webhooks deliver post-call events to your data warehouse or alerting system. Full integration with standard observability stacks.
  </Card>
</CardGroup>

## Get started

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/api-reference/installation">
    Install the SDK and trigger your first voice call. Supports Python, Node.js, Go, and React.
  </Card>

  <Card title="Create an Assistant" icon="terminal" href="/assistants/create-assistant">
    Configure an assistant with an LLM, voice, knowledge base, and deployment channels.
  </Card>

  <Card title="Connect Telephony" icon="phone" href="/voice-deployment-options/phone">
    Go live with inbound and outbound calling via your telephony provider.
  </Card>

  <Card title="Self-host" icon="server" href="/opensource/overview">
    Run the full open-source platform on your own infrastructure.
  </Card>
</CardGroup>


# Add new document
Source: https://doc.rapida.ai/knowledge/add-new-document

A simple guide to adding documents to your knowledge

Adding documents to your knowledge base is easy. Follow these steps to enhance your AI's knowledge:

<Steps>
  <Step title="Access Knowledge Base">
    Navigate to the Knowledge section in your dashboard. Open the relevant knowledge that you want to add your documents to.

    <img alt="Knowledge Base Overview" />
  </Step>

  <Step title="Choose Addition Method">
    Click on "Add document +" to start adding a new document.

    <img alt="Add Document Options" />
  </Step>

  <Step title="Select Document Type">
    Depending on your chosen method, follow the appropriate steps below.
  </Step>
</Steps>

## 1. Uploading Text Files Manually

If you're uploading a standard text file:

1. Click on "Add document manually"
2. Drag and drop your file into the upload area, or click to select from your computer.
3. Supported formats: .txt, .doc, .docx, .pdf (Max 10 MB per file)
4. Click "Upload New Document" to add it to your knowledge base.

<img alt="Upload Document" />

## 2. Adding Documents from Cloud

To import documents from cloud storage:

1. Click on "Add document from Cloud"
2. Connect to your preferred cloud service (Google Drive, Notion, etc.)
3. Select the document(s) you want to add
4. Follow the prompts to complete the import process

<img alt="Cloud Document" />

## 3. Structuring a Document

If you're adding a structured document:

1. Click on "Add catalog document"

2. Choose the document type:

   * Help / QnA (for FAQs)
   * Product Catalog
   * Blog Article

   <img alt="Select Document Type" />

3. Fill in the required fields for your chosen document type.

4. Upload any associated files if needed.

5. Click "Upload New Document" to add it to your knowledge.

After uploading, your document will be processed and integrated into the knowledge. This may take a few moments depending on the file size and complexity.

**Tip**: Adding diverse, high-quality documents improves your AI's ability to assist users effectively.


# Create knowledge
Source: https://doc.rapida.ai/knowledge/create-knowledge

Learn how to create a new knowledge base in the system

## Prerequisites

Before creating a knowledge base, ensure that you have set up an embedding model with Rapida. To set up an embedding model:

1. Navigate to the Embedding Models section in your Rapida dashboard.
2. Select the embedding model provider you want to use (e.g., OpenAI, Cohere, etc).
3. Follow the provider-specific instructions to complete the setup.

For detailed instructions on setting up embedding models, refer to the provider-specific documentation in the Embedding Models section:

* [OpenAI](/integrations/llm/openai)
* [Google AI](/integrations/llm/google-ai)
* [Cohere](/integrations/llm/cohere)

<Steps>
  <Step title="Navigate to Knowledge">
    Begin by navigating to the Knowledge section in the main navigation menu.

    <img alt="Navigate to Knowledge" />
  </Step>

  <Step title="Initiate Knowledge Base Creation">
    Click on the "Add new knowledge" button to start the process of creating a new knowledge base.

    <img alt="Initiate Knowledge Base Creation" />
  </Step>

  <Step title="Select Embedding Model and Credentials">
    First, select an appropriate embedding model for your knowledge base by clicking the dropdown menu.

    <img alt="Choose Embedding Model" />

    After selecting the embedding model provider, you'll need to select the credentials to use:

    1. Click the "Select credential" dropdown in the Credential section
    2. Choose from existing credentials for the selected provider, or click the "+" button to add a new credential
    3. If adding a new credential, you'll need to provide:
       * A name for the credential
       * The API key or required authentication information for the selected provider

    Different providers require different credential information:

    * **OpenAI**: API key
    * **VoyageAI**: API key
    * **Google AI**: API key
    * **Cohere**: API key

    For detailed instructions on setting up credentials for each provider, refer to the respective integration documentation linked in the Prerequisites section.
  </Step>

  <Step title="Enter Basic Information">
    Complete all required fields in the knowledge base creation form:

    1. **Name**: Enter a descriptive name for your knowledge base in the text field (e.g., "Our website database").
    2. **Description**: Provide a brief explanation of the purpose of this knowledge base or what type of content it contains.
    3. **Tags**: Add relevant tags to make your knowledge base easier to find. Separate tags with commas and press Enter to confirm each tag.
    4. **Review Information**: Double-check all entered information for accuracy.
    5. **Create Knowledge Base**: Click the blue "Create knowledge" button in the bottom right corner to proceed.

       <img alt="Enter Basic Information" />
  </Step>

  <Step title="Upload Content">
    Upload the relevant content for your knowledge base:

    * Drag and drop files or click to select files from your computer
    * Supported file formats will be processed and added to your knowledge base

      <img alt="Upload Content" />
  </Step>

  <Step title="Review and Create">
    Review all the information and settings for your knowledge base.
    Click "**Upload new Document**" to finalize the creation process.

    <img alt="Review and Create" />
  </Step>

  <Step title="Success Confirmation">
    You'll see a confirmation that your knowledge base has been created successfully.
    The parsing and tokenization of the documents will take a while.

    <img alt="Parsing documents" />

    Once the process is complete, you'll see a success message.

    <img alt="Document Parsing Success" />

    You can now start using your new knowledge base with assistants or upload more documents.
  </Step>
</Steps>


# Manage Document Chunks
Source: https://doc.rapida.ai/knowledge/manage-document-chunk

Learn how to manage and enhance document chunks for improved knowledge base performance

## Understanding Document Chunks

When you upload a document to your knowledge base, the system automatically divides it into smaller segments called "chunks." This chunking process is crucial for:

* **Improved LLM Processing**: Allows large language models to process manageable portions of text.
* **Enhanced Retrieval**: Enables more precise information retrieval by pinpointing relevant sections.
* **Optimized Performance**: Reduces computational load and improves response times.

## Accessing Document Chunks

<Steps>
  <Step title="Navigate to Knowledge">
    Go to the Knowledge section in the main navigation menu.
  </Step>

  <Step title="Select Knowledge Base">
    Choose the specific knowledge base containing your document.
  </Step>

  <Step title="Open Document">
    Click on the document you want to manage to view its chunks.
  </Step>

  <Step title="View Chunks">
    <img alt="Fields for segment" /> You'll see a list of
    chunks derived from the original document.
  </Step>
</Steps>

## Enhancing Document Chunks

Improve the quality of your chunks for better matching by enriching their metadata:

<Steps>
  <Step title="Open Chunk Editor">
    <img alt="Fields for segment" />

    Click on a specific chunk to open the editing interface.
  </Step>

  <Step title="Review Fields">
    Examine the automatically generated metadata fields.
  </Step>

  <Step title="Modify Information">
    Update or add details to enhance searchability and context.
  </Step>

  <Step title="Save Changes">
    Click "Update document" to apply your modifications.
  </Step>
</Steps>

### Metadata Fields

<AccordionGroup>
  <Accordion title="Document Name" icon="file">
    The title or identifier for this chunk
  </Accordion>

  <Accordion title="Organizations" icon="building">
    Relevant company or group names
  </Accordion>

  <Accordion title="Dates" icon="calendar">
    Important dates mentioned in the content
  </Accordion>

  <Accordion title="Products" icon="box">
    Product names or types discussed
  </Accordion>

  <Accordion title="Events" icon="star">
    Significant events referenced
  </Accordion>

  <Accordion title="Industries" icon="factory">
    Related industry sectors
  </Accordion>

  <Accordion title="Locations" icon="map-pin">
    Geographic locations mentioned
  </Accordion>

  <Accordion title="People" icon="user">
    Names of individuals relevant to the content
  </Accordion>
</AccordionGroup>

## Search Types

When querying your knowledge base, you can utilize different search methods:

<CardGroup>
  <Card title="Hybrid Search" icon="zoom-in">
    Combines semantic understanding with keyword matching. Ideal for balancing
    context-aware results with exact matches.
  </Card>

  <Card title="Full Text Search" icon="type">
    Focuses on exact keyword matches within the text. Best for finding specific
    terms or phrases.
  </Card>

  <Card title="Semantic Search" icon="brain">
    Emphasizes understanding the meaning and context of the query. Excellent for
    natural language queries and user intent.
  </Card>
</CardGroup>

Choose the search type that best fits your specific use case and the nature of your queries to optimize your knowledge base performance.


# Overview
Source: https://doc.rapida.ai/knowledge/overview

Enhance your AI applications with powerful knowledge integration

Knowledge is a crucial component for enhancing AI applications, especially when working with Large Language Models (LLMs). It serves as a repository of information that can be leveraged to improve the accuracy, relevance, and capabilities of AI interactions.

<img alt="Rapida Knowledge Overview" />

## What is Knowledge in AI Context?

In the context of AI applications, knowledge refers to a collection of documents, data, or information that can be used to augment the capabilities of language models. It acts as a specialized database that the AI can reference to provide more accurate and contextually relevant responses.

## Key Use Cases

Knowledge integration can be utilized in various ways to enhance your AI application's capabilities:

<CardGroup>
  <Card title="Contextual Responses" icon="message-square">
    Provide more accurate and relevant responses by referencing specific domain knowledge.
  </Card>

  <Card title="Information Retrieval" icon="database">
    Quickly access and retrieve specific information from a large corpus of documents.
  </Card>
</CardGroup>

## Benefits and Capabilities

Utilizing knowledge integration offers several advantages:

<CardGroup>
  <Card title="Tag Solutions" icon="tags">
    Organize and categorize information for easy retrieval and association with
    AI assistants.
  </Card>

  <Card title="Tool Calls" icon="wrench">
    Enable AI to make specific calls to knowledge bases for targeted information
    retrieval.
  </Card>

  <Card title="Custom Knowledge Bases" icon="book">
    Create and maintain specialized knowledge bases tailored to your
    application's needs.
  </Card>

  <Card title="Dynamic Updates" icon="refresh-cw">
    Easily update and expand your knowledge base without retraining the entire
    model.
  </Card>

  <Card title="Multi-format Support" icon="file-text">
    Incorporate various document formats including text, PDFs, and structured
    data.
  </Card>

  <Card title="Semantic Search" icon="brain">
    Implement advanced search capabilities to find relevant information beyond
    keyword matching, understanding context and meaning.
  </Card>

  <Card title="Hybrid Search" icon="git-merge">
    Combine semantic and keyword-based approaches for more accurate and
    comprehensive search results.
  </Card>

  <Card title="Full Text Search" icon="search">
    Enable comprehensive content analysis and retrieval, allowing users to
    search through entire documents efficiently.
  </Card>
</CardGroup>

## Conclusion

Knowledge integration is a powerful tool that allows you to enhance the capabilities of your AI applications. By leveraging these key use cases and benefits, you can create more sophisticated, accurate, and context-aware AI features. Properly implemented knowledge bases open up a world of possibilities for improving your application's intelligence and user experience.


# Architecture Overview
Source: https://doc.rapida.ai/opensource/architecture

System architecture, service topology, and data flows for the Rapida Voice AI Platform

## System Architecture

Rapida is a Go-based microservices platform (module: `github.com/rapidaai`, Go 1.25). Services communicate over gRPC internally and expose REST and gRPC-web APIs via a shared Nginx gateway on port 8080. A single TCP port per service multiplexes HTTP/2 (gRPC), grpc-web, and HTTP/1.1 using [cmux](https://github.com/soheilhy/cmux).

```mermaid theme={null}
graph TD
    subgraph Clients
        Browser["Browser / Web App"]
        Phone["Phone / SIP Client"]
        SDK["Server SDK (Go · Python · Node)"]
    end

    Nginx["Nginx Gateway :8080\n(Reverse Proxy · SSL/TLS · gRPC-Web)"]

    subgraph Services["Rapida Services"]
        UI["ui :3000\nReact Dashboard"]
        WebAPI["web-api :9001\nAuth · Orgs · Vault"]
        AssistantAPI["assistant-api :9007\nVoice Orchestration\nSTT · LLM · TTS\nSIP :4573"]
        IntegrationAPI["integration-api :9004\nLLM / STT / TTS\nProvider Integrations"]
        EndpointAPI["endpoint-api :9005\nWebhooks · Callbacks"]
        DocumentAPI["document-api :9010\nRAG · Embeddings\nKnowledge Base"]
    end

    subgraph Infra["Infrastructure"]
        PG[("PostgreSQL :5432")]
        Redis[("Redis :6379")]
        OS[("OpenSearch :9200")]
    end

    subgraph Providers["External Providers"]
        LLMs["LLMs\nOpenAI · Anthropic · Gemini\nAzure · Bedrock · Mistral · Cohere"]
        STT_P["STT\nDeepgram · Google · Azure\nAssemblyAI · Cartesia"]
        TTS_P["TTS\nElevenLabs · Azure · Google\nDeepgram · Cartesia"]
        Tel["Telephony\nTwilio · Vonage · Exotel · SIP"]
    end

    Browser --> Nginx
    SDK --> Nginx
    Phone -->|"SIP :4573 / AudioSocket"| AssistantAPI
    Nginx --> UI
    Nginx --> WebAPI
    Nginx -->|"WebSocket upgrade\n/talk_api.TalkService/AssistantTalk"| AssistantAPI
    Nginx -->|"gRPC-web / REST\n/talk_api · /web_api · /vault_api ..."| WebAPI

    WebAPI -->|gRPC| AssistantAPI
    WebAPI -->|gRPC| IntegrationAPI
    WebAPI -->|gRPC| EndpointAPI
    WebAPI -->|HTTP| DocumentAPI
    AssistantAPI -->|gRPC| IntegrationAPI
    AssistantAPI -->|gRPC| EndpointAPI

    WebAPI --> PG
    AssistantAPI --> PG
    IntegrationAPI --> PG
    EndpointAPI --> PG
    DocumentAPI --> PG

    WebAPI --> Redis
    AssistantAPI --> Redis
    DocumentAPI --> Redis

    AssistantAPI --> OS
    DocumentAPI --> OS

    IntegrationAPI --> LLMs
    IntegrationAPI --> STT_P
    IntegrationAPI --> TTS_P
    AssistantAPI --> Tel
```

***

## Service Responsibilities

| Service                       | Port | Language | Responsibility                                                       |
| ----------------------------- | ---- | -------- | -------------------------------------------------------------------- |
| **web-api**                   | 9001 | Go       | Auth, organizations, projects, credential vault                      |
| **assistant-api**             | 9007 | Go       | Voice orchestration, STT/TTS pipeline, telephony                     |
| **integration-api**           | 9004 | Go       | LLM/STT/TTS provider integrations, OAuth                             |
| **endpoint-api**              | 9005 | Go       | Webhook management, event routing, retry                             |
| **document-api** *(optional)* | 9010 | Python   | Document processing, embeddings, RAG (FastAPI) — knowledge base only |
| **ui**                        | 3000 | React/TS | Frontend dashboard                                                   |
| **nginx**                     | 8080 | —        | Reverse proxy, WebSocket upgrade, SSL/TLS                            |

<Info>
  **document-api** and **opensearch** are optional. They are only needed for knowledge base / RAG features. Voice assistants (STT/LLM/TTS) work fully without them.
</Info>

***

## Nginx Routing

The Nginx gateway at port 8080 routes requests based on the gRPC service path prefix:

| Path Pattern                                                                                                            | Upstream           | Protocol          |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------- |
| `/talk_api.TalkService/AssistantTalk`                                                                                   | assistant-api:9007 | WebSocket upgrade |
| `/talk_api`                                                                                                             | assistant-api:9007 | gRPC-web          |
| `/tool_api`, `/web_api`, `/vault_api`, `/workflow_api`, `/assistant_api`, `/knowledge_api`, `/connect_api`, `/lead_api` | web-api:9001       | gRPC-web          |
| `/rapida-data/assets/workflow/`                                                                                         | Static files       | HTTP              |
| `/`                                                                                                                     | web-api:9001       | HTTP proxy        |

> **Real-time audio** connections use the WebSocket upgrade path. The browser SDK connects to `ws://hostname:8080/talk_api.TalkService/AssistantTalk` for bidirectional audio streaming.

***

## Data Layer

### PostgreSQL Databases

PostgreSQL 15 is the primary relational store. Each service owns a dedicated database. The `init.sql` initializes all required databases on first container start.

| Database         | Owners                      | Purpose                                          |
| ---------------- | --------------------------- | ------------------------------------------------ |
| `web_db`         | web-api                     | Users, organizations, projects, API keys, vault  |
| `assistant_db`   | assistant-api, document-api | Assistants, conversations, messages, embeddings  |
| `integration_db` | integration-api             | Integrations, provider credentials, OAuth tokens |
| `endpoint_db`    | endpoint-api                | Webhooks, endpoints, delivery logs               |

```
PostgreSQL :5432
├── web_db        ← web-api
├── assistant_db  ← assistant-api + document-api
├── integration_db ← integration-api
└── endpoint_db   ← endpoint-api
```

> The `web_db` is defined as the default database in `POSTGRES_DB` in docker-compose and created automatically by the PostgreSQL image. The remaining three databases are created by `docker/postgres/init.sql`.

### Redis Databases

Redis 7 serves as the in-memory cache, session store, and job broker.

| DB | Purpose                                             |
| -- | --------------------------------------------------- |
| 0  | General application cache (GORM second-level cache) |
| 1  | Session / auth token cache                          |
| 2  | Celery job broker (document-api background jobs)    |

### OpenSearch Indices (Optional — Knowledge Base Only)

OpenSearch 2.11.1 handles full-text search and vector similarity search. It is only required when running with the knowledge base profile (`make up-all-with-knowledge`).

| Index                     | Producer      | Purpose                              |
| ------------------------- | ------------- | ------------------------------------ |
| `assistant-conversations` | assistant-api | Searchable conversation transcripts  |
| `conversation-metrics`    | assistant-api | Call latency and quality metrics     |
| `documents-*`             | document-api  | Knowledge base chunks and embeddings |
| `logs-*`                  | assistant-api | Structured application logs          |

***

## Data Flows

### 1. User Authentication

```mermaid theme={null}
sequenceDiagram
    participant UI as Browser (UI :3000)
    participant Nginx as Nginx :8080
    participant Web as web-api :9001
    participant PG as PostgreSQL (web_db)
    participant Cache as Redis

    UI->>Nginx: POST /web_api.AuthService/Login
    Nginx->>Web: gRPC-web forward
    Web->>PG: Verify credentials
    PG-->>Web: User record
    Web->>Cache: Store session token
    Web-->>UI: JWT + refresh token
```

### 2. Voice Conversation

```mermaid theme={null}
sequenceDiagram
    participant Client as Phone / Browser
    participant Nginx as Nginx :8080
    participant Asst as assistant-api :9007
    participant Integ as integration-api :9004
    participant LLM as LLM Provider
    participant STT as STT Provider
    participant TTS as TTS Provider
    participant PG as PostgreSQL
    participant OS as OpenSearch
    participant EP as endpoint-api :9005

    Client->>Nginx: WebSocket /talk_api.TalkService/AssistantTalk
    Nginx->>Asst: WebSocket upgrade (keepalive 64)
    Asst->>PG: Create conversation record
    Client->>Asst: Stream PCM / G.711 audio
    Asst->>Asst: VAD: voice activity detected
    Asst->>STT: Stream audio chunks
    STT-->>Asst: Transcribed text
    Asst->>Integ: gRPC: execute LLM with transcript + context
    Integ->>LLM: Forward with system prompt + history
    LLM-->>Integ: Stream response tokens
    Integ-->>Asst: Streamed tokens
    Asst->>TTS: Text → audio synthesis
    TTS-->>Asst: Audio chunks
    Asst-->>Client: Stream synthesized audio
    Asst->>PG: Persist messages (assistant_db)
    Asst->>OS: Index conversation transcript
    Asst->>EP: gRPC: fire conversation.message webhook
    EP->>EP: Deliver to registered endpoints (with retry)
```

### 3. Inbound Phone Call (Twilio / Vonage)

```mermaid theme={null}
sequenceDiagram
    participant Tel as Telephony Provider
    participant Asst as assistant-api :9007
    participant Integ as integration-api :9004
    participant EP as endpoint-api :9005

    Tel->>Asst: Webhook: inbound call event
    Asst->>Asst: Resolve assistant for this number
    Asst->>Integ: Fetch LLM + STT + TTS credentials
    Tel->>Asst: Stream audio (WebSocket / SIP)
    Note over Asst: STT → LLM → TTS pipeline runs
    Asst-->>Tel: Stream synthesized audio
    Asst->>EP: Fire conversation.started webhook
    Tel->>Asst: Call ended
    Asst->>EP: Fire conversation.ended webhook
```

### 4. SIP / Asterisk Connection

```mermaid theme={null}
sequenceDiagram
    participant Asterisk as Asterisk PBX
    participant Asst as assistant-api :4573

    Asterisk->>Asst: AudioSocket TCP connect :4573
    Asst->>Asst: Resolve assistant configuration
    Asterisk->>Asst: Stream G.711 µ-law audio frames
    Asst-->>Asterisk: Stream synthesized audio frames
    Asterisk->>Asst: Hangup signal
    Asst->>Asst: End conversation, persist record
```

### 5. Document Upload and RAG Indexing

```mermaid theme={null}
sequenceDiagram
    participant UI as Dashboard (UI)
    participant Web as web-api :9001
    participant Doc as document-api :9010
    participant PG as PostgreSQL (assistant_db)
    participant Redis as Redis (Celery queue)
    participant OS as OpenSearch

    UI->>Web: Upload document (PDF/DOCX/etc.)
    Web->>Doc: HTTP POST /api/v1/document/upload
    Doc->>PG: Store document metadata
    Doc->>Redis: Enqueue process_document Celery task
    Doc-->>Web: { document_id, status: "processing" }
    Redis->>Doc: Worker picks up task
    Doc->>Doc: Extract text → chunk → embed
    Doc->>PG: Store chunks + embeddings
    Doc->>OS: Index chunks for full-text search
    Doc->>PG: Update status: "completed"
```

***

## Communication Patterns

### Synchronous

| Pattern       | Used For                                     | Implementation          |
| ------------- | -------------------------------------------- | ----------------------- |
| **REST/HTTP** | External-facing API calls, health checks     | Gin framework           |
| **gRPC**      | Inter-service calls (typed, schema-enforced) | gRPC + protobuf         |
| **gRPC-web**  | Browser → backend (gRPC over HTTP/1.1)       | improbable-eng grpc-web |
| **WebSocket** | Real-time audio streaming (assistant-api)    | gorilla/websocket       |

### Asynchronous

| Pattern           | Used For                                  | Implementation |
| ----------------- | ----------------------------------------- | -------------- |
| **Redis Pub/Sub** | Real-time session updates, notifications  | go-redis       |
| **Celery tasks**  | Document processing, embedding generation | Redis broker   |
| **Webhooks**      | External event delivery with retry        | endpoint-api   |

***

## Port Reference

| Service         | Port | Protocol                | Notes                                       |
| --------------- | ---- | ----------------------- | ------------------------------------------- |
| nginx           | 8080 | HTTP / WebSocket        | External entry point                        |
| ui              | 3000 | HTTP                    | React development server / production build |
| web-api         | 9001 | HTTP + gRPC + gRPC-web  | cmux multiplexed                            |
| assistant-api   | 9007 | HTTP + gRPC + WebSocket | cmux multiplexed; real-time audio           |
| assistant-api   | 4573 | TCP (AudioSocket)       | Asterisk AudioSocket integration            |
| integration-api | 9004 | HTTP + gRPC             | cmux multiplexed                            |
| endpoint-api    | 9005 | HTTP + gRPC             | cmux multiplexed                            |
| document-api    | 9010 | HTTP (FastAPI)          | ASGI / uvicorn                              |
| PostgreSQL      | 5432 | TCP                     | Internal only (not exposed publicly)        |
| Redis           | 6379 | TCP                     | Internal only                               |
| OpenSearch      | 9200 | HTTP                    | Internal; 9600 for metrics                  |

***

## Scaling

All application services are stateless and scale horizontally behind the Nginx load balancer.

```mermaid theme={null}
graph LR
    LB["Nginx\nLoad Balancer"]
    LB --> wa1["web-api-1"]
    LB --> wa2["web-api-2"]
    LB --> aa1["assistant-api-1"]
    LB --> aa2["assistant-api-2"]
    LB --> ia1["integration-api-1"]
    LB --> ea1["endpoint-api-1"]

    subgraph Stateful
        PG[("PostgreSQL\nvertical / read replicas")]
        Redis[("Redis\ncluster mode")]
        OS[("OpenSearch\nhorizontal sharding")]
    end

    wa1 & wa2 & aa1 & aa2 & ia1 & ea1 --> PG
    wa1 & wa2 & aa1 & aa2 --> Redis
    aa1 & aa2 --> OS
```

| Layer       | Scaling Strategy                       |
| ----------- | -------------------------------------- |
| Application | Horizontal (stateless pods/containers) |
| PostgreSQL  | Vertical + read replicas               |
| Redis       | Vertical or cluster mode               |
| OpenSearch  | Horizontal (node count + shard count)  |

***

## Next Steps

* [Installation](/opensource/installation) — Deploy locally with Docker Compose
* [Configuration](/opensource/configuration) — Environment variable reference
* [Services Overview](/opensource/services) — Per-service documentation


# Configuration Reference
Source: https://doc.rapida.ai/opensource/configuration

Complete configuration options for Rapida services

### Global Configuration

These variables apply to all services:

| Variable       | Type   | Default      | Description                                   |
| -------------- | ------ | ------------ | --------------------------------------------- |
| `SERVICE_NAME` | string | service name | Service identifier for logging                |
| `HOST`         | string | 0.0.0.0      | Bind address (0.0.0.0 = all interfaces)       |
| `PORT`         | int    | varies       | Service port number                           |
| `LOG_LEVEL`    | string | info         | Logging level: debug, info, warn, error       |
| `ENV`          | string | development  | Environment: development, staging, production |
| `SECRET`       | string | rpd\_pks     | Encryption secret key                         |

### Example Global Config

```env theme={null}
SERVICE_NAME=web-api
HOST=0.0.0.0
PORT=9001
LOG_LEVEL=debug
ENV=development
SECRET=your_encryption_secret_here
```

## Database Configuration

### PostgreSQL

All services connect to PostgreSQL with similar configuration:

```env theme={null}
# Connection settings
POSTGRES__HOST=localhost          # Database host
POSTGRES__PORT=5432               # PostgreSQL port
POSTGRES__DB_NAME=web_db          # Database name
POSTGRES__AUTH__USER=rapida_user  # Database user
POSTGRES__AUTH__PASSWORD=rapida_db_password  # Database password
POSTGRES__SSL_MODE=disable        # SSL mode: disable, require, prefer

# Connection pooling
POSTGRES__MAX_OPEN_CONNECTION=10     # Max open connections
POSTGRES__MAX_IDEAL_CONNECTION=5     # Ideal idle connections

# Query timeouts
POSTGRES__STATEMENT_TIMEOUT=0     # Query timeout (0 = no limit)
POSTGRES__IDLE_TIMEOUT=600        # Connection idle timeout (seconds)
```

### Connection String Format

Manual connection string:

```
postgresql://rapida_user:rapida_db_password@localhost:5432/web_db?sslmode=disable
```

### Database Selection

| Service         | Database        | Purpose                                     |
| --------------- | --------------- | ------------------------------------------- |
| web-api         | web\_db         | Users, organizations, projects, credentials |
| assistant-api   | assistant\_db   | Assistants, conversations, deployments      |
| integration-api | integration\_db | Provider credentials, configurations        |
| endpoint-api    | endpoint\_db    | Webhooks, endpoints, callbacks              |
| document-api    | assistant\_db   | Documents, embeddings, knowledge base       |

### Connection Pooling for Performance

```env theme={null}
# Development
POSTGRES__MAX_OPEN_CONNECTION=5
POSTGRES__MAX_IDEAL_CONNECTION=2

# Production
POSTGRES__MAX_OPEN_CONNECTION=20
POSTGRES__MAX_IDEAL_CONNECTION=10
```

## Redis Configuration

```env theme={null}
# Connection settings
REDIS__HOST=localhost           # Redis host
REDIS__PORT=6379                # Redis port
REDIS__AUTH__USER=               # Redis username (if auth enabled)
REDIS__AUTH__PASSWORD=           # Redis password (if auth enabled)
REDIS__DB=0                      # Redis database number (0-15)

# Connection pooling
REDIS__MAX_CONNECTION=10         # Maximum connections in pool

# Timeout settings
REDIS__DIAL_TIMEOUT=5            # Connection timeout (seconds)
REDIS__READ_TIMEOUT=3            # Read timeout (seconds)
REDIS__WRITE_TIMEOUT=3           # Write timeout (seconds)

# TLS (if enabled)
REDIS__TLS__ENABLED=false        # Enable TLS
REDIS__TLS__INSECURE=false       # Skip cert validation
```

### Redis Database Usage

| DB | Purpose                 |
| -- | ----------------------- |
| 0  | General cache           |
| 1  | Session cache           |
| 2  | Rate limiting           |
| 3+ | Reserved for extensions |

### Redis Performance Tuning

```env theme={null}
# For high traffic
REDIS__MAX_CONNECTION=30
REDIS__DIAL_TIMEOUT=10
```

## OpenSearch Configuration (Optional — Knowledge Base Only)

OpenSearch is only required when using the knowledge base / RAG features. If `OPENSEARCH__HOST` is not set (or left empty), the assistant-api starts without knowledge base support and no connection to OpenSearch is attempted.

```env theme={null}
# Connection settings
OPENSEARCH__SCHEMA=http          # http or https
OPENSEARCH__HOST=opensearch      # OpenSearch host (leave empty to disable knowledge base)
OPENSEARCH__PORT=9200            # OpenSearch port
OPENSEARCH__USERNAME=            # Username (if auth enabled)
OPENSEARCH__PASSWORD=            # Password (if auth enabled)

# Performance
OPENSEARCH__MAX_RETRIES=3        # Max retry attempts
OPENSEARCH__MAX_CONNECTION=10    # Max connections
OPENSEARCH__TIMEOUT=30           # Request timeout (seconds)

# Batch settings
OPENSEARCH__BATCH_SIZE=1000      # Documents per batch
OPENSEARCH__FLUSH_INTERVAL=5     # Batch flush interval (seconds)
```

### OpenSearch Indices

| Index Name              | Purpose                      |
| ----------------------- | ---------------------------- |
| assistant-conversations | Conversation transcripts     |
| logs-\*                 | Service and application logs |
| documents-\*            | Knowledge base documents     |

### OpenSearch Index Configuration

```yaml theme={null}
# Index settings for assistant-conversations
{
  "settings":
    {
      "number_of_shards": 1,
      "number_of_replicas": 0,
      "refresh_interval": "30s",
    },
  "mappings":
    {
      "properties":
        {
          "conversation_id": { "type": "keyword" },
          "content": { "type": "text" },
          "timestamp": { "type": "date" },
        },
    },
}
```

## Service-Specific Configuration

### Web API (.web.env)

```env theme={null}
SERVICE_NAME=web-api
HOST=0.0.0.0
PORT=9001
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# Database
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=web_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432
POSTGRES__MAX_OPEN_CONNECTION=10
POSTGRES__MAX_IDEAL_CONNECTION=10
POSTGRES__SSL_MODE=disable

# Cache
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__AUTH__PASSWORD=
POSTGRES__SLC_CACHE__AUTH__USER=
POSTGRES__SLC_CACHE__MAX_CONNECTION=10
POSTGRES__SLC_CACHE__DB=1

# Redis
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=5

# Asset storage
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/web

# Internal services
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
DOCUMENT_HOST=http://document-api:9010  # Optional — only needed when using knowledge base
UI_HOST=https://localhost:3000
```

### Assistant API (.assistant.env)

```env theme={null}
SERVICE_NAME=workflow-api
HOST=0.0.0.0
PORT=9007
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# Asset storage
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/workflow

# PostgreSQL
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=assistant_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432
POSTGRES__MAX_OPEN_CONNECTION=50
POSTGRES__MAX_IDEAL_CONNECTION=25
POSTGRES__SSL_MODE=disable

# Redis cache
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__AUTH__PASSWORD=
POSTGRES__SLC_CACHE__AUTH__USER=
POSTGRES__SLC_CACHE__MAX_CONNECTION=10
POSTGRES__SLC_CACHE__DB=1

# Redis
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__AUTH__PASSWORD=
REDIS__AUTH__USER=
REDIS__MAX_CONNECTION=10
REDIS__MAX_DB=0

# OpenSearch — optional, only needed for knowledge base features
# Leave OPENSEARCH__HOST empty (or remove these lines) to run without knowledge base
OPENSEARCH__SCHEMA=http
OPENSEARCH__HOST=opensearch
OPENSEARCH__PORT=9200
OPENSEARCH__MAX_RETRIES=3
OPENSEARCH__MAX_CONNECTION=10

# Internal services
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
```

### Integration API (.integration.env)

```env theme={null}
SERVICE_NAME=integration-api
HOST=0.0.0.0
PORT=9004
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# Database
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=integration_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432
POSTGRES__MAX_OPEN_CONNECTION=10

# Redis
REDIS__HOST=redis
REDIS__PORT=6379

# Encryption for stored credentials
INTEGRATION_CRYPTO_KEY=your_encryption_key_here

# Internal services
WEB_HOST=web-api:9001
```

### Endpoint API (.endpoint.env)

```env theme={null}
SERVICE_NAME=endpoint-api
HOST=0.0.0.0
PORT=9005
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# Database
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=endpoint_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432

# Webhook configuration
WEBHOOK__TIMEOUT=30              # Webhook call timeout (seconds)
WEBHOOK__MAX_RETRIES=3           # Max webhook retries
WEBHOOK__RETRY_DELAY=5           # Retry delay (seconds)
```

### Document API (config.yaml)

```yaml theme={null}
service_name: "Document API"
host: "0.0.0.0"
port: 9010

authentication_config:
  strict: false
  type: "jwt"
  config:
    secret_key: "rpd_pks"

# Elasticsearch/OpenSearch
elastic_search:
  host: "localhost"
  port: 9200
  scheme: "http"
  max_connection: 5

# PostgreSQL
postgres:
  host: "localhost"
  port: 5432
  auth:
    password: "rapida_db_password"
    user: "rapida_user"
  db: "assistant_db"
  max_connection: 10
  ideal_connection: 5

# Internal services
internal_service:
  web_host: "localhost:9001"
  integration_host: "localhost:9004"
  endpoint_host: "localhost:9005"
  assistant_host: "localhost:9006"

# File storage
storage:
  storage_type: "local"
  storage_path_prefix: ~/rapida-data/assets/workflow

# Message queue for background jobs
celery:
  broker: "redis://localhost:6379/0"
  backend: "redis://localhost:6379/0"

# Knowledge extraction configuration
knowledge_extractor_config:
  chunking_technique:
    chunker: "app.core.chunkers.statistical_chunker.StatisticalChunker"
    options:
      encoder: "app.core.encoders.openai_encoder.OpenaiEncoder"
      options:
        model_name: "text-embedding-3-large"
        api_key: "your_openai_api_key"
```

## Logging Configuration

### Log Levels

| Level   | Use Case                        |
| ------- | ------------------------------- |
| `debug` | Development - very verbose      |
| `info`  | Production - standard info logs |
| `warn`  | Production - warnings only      |
| `error` | Production - errors only        |

### Changing Log Level

```env theme={null}
# In environment file
LOG_LEVEL=info

# At runtime (some services support this)
curl -X POST http://localhost:9001/api/v1/config/loglevel \
  -H "Content-Type: application/json" \
  -d '{"level":"debug"}'
```

## Storage Configuration

### Local Storage

```env theme={null}
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/web
```

**Requires**:

* Writable directory at path
* Sufficient disk space
* Proper permissions

### S3 Storage (AWS)

```env theme={null}
ASSET_STORE__STORAGE_TYPE=s3
ASSET_STORE__S3__BUCKET=rapida-assets
ASSET_STORE__S3__REGION=us-east-1
ASSET_STORE__S3__ACCESS_KEY_ID=your_access_key
ASSET_STORE__S3__SECRET_ACCESS_KEY=your_secret_key
ASSET_STORE__S3__ENDPOINT=https://s3.amazonaws.com
```

### Azure Blob Storage

```env theme={null}
ASSET_STORE__STORAGE_TYPE=azure
ASSET_STORE__AZURE__CONTAINER=rapida-assets
ASSET_STORE__AZURE__ACCOUNT_NAME=your_account
ASSET_STORE__AZURE__ACCOUNT_KEY=your_key
```

## Security Configuration

### JWT Authentication

```env theme={null}
# Shared across services
SECRET=your_jwt_secret_key_here

# Recommended: Use strong 32+ character keys
# Generate: openssl rand -hex 32
```

### Credential Encryption

```env theme={null}
# For Integration API
INTEGRATION_CRYPTO_KEY=your_encryption_key_here
```

### TLS/SSL

```env theme={null}
# For HTTPS
TLS__ENABLED=true
TLS__CERT_PATH=/path/to/cert.pem
TLS__KEY_PATH=/path/to/key.pem
```

### CORS Configuration

```env theme={null}
CORS__ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
CORS__ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS__ALLOWED_HEADERS=Content-Type,Authorization
CORS__ALLOW_CREDENTIALS=true
```

## Performance Tuning

### High-Traffic Configuration

```env theme={null}
# Database
POSTGRES__MAX_OPEN_CONNECTION=50
POSTGRES__MAX_IDEAL_CONNECTION=25

# Redis
REDIS__MAX_CONNECTION=30

# OpenSearch
OPENSEARCH__MAX_CONNECTION=20
OPENSEARCH__BATCH_SIZE=5000
OPENSEARCH__FLUSH_INTERVAL=10

# Caching
CACHE__DEFAULT_TTL=300
CACHE__LONG_TTL=3600
```

### Low-Resource Configuration

```env theme={null}
# Database
POSTGRES__MAX_OPEN_CONNECTION=5
POSTGRES__MAX_IDEAL_CONNECTION=2

# Redis
REDIS__MAX_CONNECTION=5

# OpenSearch
OPENSEARCH__MAX_CONNECTION=5
OPENSEARCH__BATCH_SIZE=100
OPENSEARCH__FLUSH_INTERVAL=5

# Logging
LOG_LEVEL=warn
```

## Multi-Environment Setup

### Development

```env theme={null}
ENV=development
LOG_LEVEL=debug
POSTGRES__SSL_MODE=disable
```

### Staging

```env theme={null}
ENV=staging
LOG_LEVEL=info
POSTGRES__SSL_MODE=prefer
POSTGRES__MAX_OPEN_CONNECTION=20
```

### Production

```env theme={null}
ENV=production
LOG_LEVEL=warn
POSTGRES__SSL_MODE=require
POSTGRES__MAX_OPEN_CONNECTION=50
TLS__ENABLED=true
CACHE__DEFAULT_TTL=600
```

## Feature Flags

Some services support feature flags:

```env theme={null}
FEATURE_FLAGS__ADVANCED_ANALYTICS=true
FEATURE_FLAGS__WEBHOOKS=true
FEATURE_FLAGS__RAG=true
FEATURE_FLAGS__CUSTOM_MODELS=false
```

## Configuration Validation

### Checking Configuration

```bash theme={null}
# Export and verify environment variables
export $(cat env/.web.env | xargs)
env | grep POSTGRES
env | grep REDIS

# Test database connection
psql $POSTGRES__HOST ...
```

### Health Checks

Each service exposes two endpoints:

```bash theme={null}
# Readiness — service is ready to accept traffic
curl http://localhost:9001/readiness/

# Liveness — service process is healthy
curl http://localhost:9001/healthz/
```

Replace `9001` with the target service port (`9004`, `9005`, `9007`, `9010`).

## Configuration Best Practices

1. **Never commit secrets** - Use `.env.example` templates
2. **Environment parity** - Keep dev/staging/prod similar
3. **Document changes** - Keep track of configuration changes
4. **Use strong secrets** - Min 32 characters for encryption keys
5. **Monitor configuration** - Log configuration changes
6. **Regular rotation** - Rotate secrets periodically
7. **Principle of least privilege** - Only grant needed permissions
8. **Infrastructure as Code** - Store configs in version control (without secrets)

## Updating Configuration

### With Docker

```bash theme={null}
# Edit environment file
nano docker/web-api/.web.env

# Restart service
docker compose restart web-api
```

### Without Docker

```bash theme={null}
# Edit environment file
nano env/.web.env

# Source environment
export $(cat env/.web.env | xargs)

# Restart service (kill and restart process)
```

## Configuration Secrets Management

### Using Environment Variables

```bash theme={null}
# Export from shell
export POSTGRES__AUTH__PASSWORD="your_password"

# Or from file
export $(cat .env.production | xargs)
```

### Using Secret Management Tools

**AWS Secrets Manager**:

```bash theme={null}
aws secretsmanager get-secret-value --secret-id rapida/db-password
```

**HashiCorp Vault**:

```bash theme={null}
vault kv get secret/rapida/db-password
```

**Kubernetes Secrets**:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: rapida-secrets
type: Opaque
stringData:
  postgres-password: "your_password"
  redis-password: "your_password"
```

## Troubleshooting Configuration

### Service Won't Connect to Database

```bash theme={null}
# Check variables
echo $POSTGRES__HOST
echo $POSTGRES__PORT

# Test connection
psql -h $POSTGRES__HOST -U $POSTGRES__AUTH__USER -d $POSTGRES__DB_NAME

# Verify in env file
cat env/.web.env | grep POSTGRES
```

### Cache Not Working

```bash theme={null}
# Check Redis connection
redis-cli -h $REDIS__HOST -p $REDIS__PORT ping

# Verify configuration
echo $REDIS__HOST $REDIS__PORT

# Check logs for connection errors
tail -f service.log | grep redis
```

### Search Not Working

```bash theme={null}
# Check OpenSearch connection
curl http://$OPENSEARCH__HOST:$OPENSEARCH__PORT/_cluster/health

# Verify indices exist
curl http://$OPENSEARCH__HOST:$OPENSEARCH__PORT/_cat/indices
```

## Next Steps

1. [Getting Started](/introduction/overview) - Build your first assistant
2. [Installation](/opensource/installation) - Install Rapida with Docker or manually


# Installation
Source: https://doc.rapida.ai/opensource/installation

Get Rapida up and running with the deployment model that fits your ownership and scale requirements

## Choose deployment mode

Select one mode before running commands:

### Voice Only (Recommended)

* Use this for voice assistants that call LLM providers directly and you want the smallest controlled deployment footprint.
* Services started: `ui`, `nginx`, `web-api`, `assistant-api`, `integration-api`, `endpoint-api`, `postgres`, `redis`
* Minimum RAM: 4 GB
* Start command (builds and starts): `make up-all`
* Optional pre-build command: `make build-all`

```bash theme={null}
make up-all
```

### Voice + Knowledge Base

* Use this if teams or clients need private document retrieval (RAG) in the same controlled environment.
* Adds: `document-api` and `opensearch`
* Minimum RAM: 8 to 16 GB
* Start command (builds and starts): `make up-all-with-knowledge`
* Optional pre-build command: `make build-all-with-knowledge`

```bash theme={null}
make up-all-with-knowledge
```

You can start with Voice Only and switch later by running `make up-all-with-knowledge`. Existing PostgreSQL and Redis data is not changed.

***

<Tabs>
  <Tab title="Docker (Recommended)">
    The fastest way to get Rapida running on infrastructure your team controls. Best for agencies, internal platform teams, and enterprise environments that need ownership of keys, networking, and runtime behavior.

    ### Prerequisites

    * [Docker Desktop](https://www.docker.com/products/docker-desktop) or Docker Engine (v20.10+)
    * Docker Compose (v2.0+) - included with Docker Desktop
    * 4GB+ RAM available
    * 10GB free disk space

    **Apple Silicon (M1/M2/M3/M4):** Rapida base images are built for `linux/amd64`. The `Makefile` sets `DOCKER_DEFAULT_PLATFORM=linux/amd64` automatically for all `make` commands. Use `make` commands instead of running `docker compose build` directly.

    ### Installation Steps

    <Steps>
      <Step title="Install Docker and Docker Compose">
        <CodeGroup>
          ```bash macOS theme={null}
          # Using Homebrew
          brew install --cask docker

          # Or download from Docker website
          # https://www.docker.com/products/docker-desktop

          # Then open Docker.app from Applications folder.
          ```

          ```bash Linux (Ubuntu/Debian) theme={null}
          # Install Docker
          curl -fsSL https://get.docker.com -o get-docker.sh
          sudo sh get-docker.sh

          # Install Docker Compose
          sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
          sudo chmod +x /usr/local/bin/docker-compose

          # Add your user to docker group (avoid sudo)
          sudo usermod -aG docker $USER
          newgrp docker
          ```

          ```bash Windows (WSL2) theme={null}
          # Using Windows Package Manager
          winget install Docker.DockerDesktop

          # Or download from Docker website
          # https://www.docker.com/products/docker-desktop

          # Ensure WSL2 is enabled in Docker Desktop settings.
          ```
        </CodeGroup>
      </Step>

      <Step title="Verify Installation">
        ```bash theme={null}
        # Check Docker
        docker --version
        # Expected: Docker version 20.10+

        # Check Docker Compose
        docker compose version
        # Expected: version 2.0+

        # Test Docker
        docker run hello-world
        ```
      </Step>

      <Step title="Clone Repository">
        ```bash theme={null}
        git clone https://github.com/rapidaai/voice-ai.git
        cd voice-ai
        ```
      </Step>

      <Step title="Run Setup">
        ```bash theme={null}
        # Create data directories and set permissions
        make setup-local
        ```

        This creates:

        * `~/rapida-data/assets/db` - PostgreSQL
        * `~/rapida-data/assets/redis` - Redis
        * `~/rapida-data/assets/opensearch` - OpenSearch (only used with the knowledge base profile)
      </Step>

      <Step title="Run preflight checks (recommended)">
        ```bash theme={null}
        make doctor
        ```

        This validates Docker daemon access, Docker Compose availability, memory/disk constraints, and common local port conflicts.
      </Step>

      <Step title="Start Rapida">
        <Tabs>
          <Tab title="Voice Only (recommended)">
            Starts all core services: web-api, assistant-api, integration-api, endpoint-api, UI, PostgreSQL, Redis, and Nginx.
            `document-api` and `opensearch` are **not started**.
            This command also builds required images in low-memory mode.

            ```bash theme={null}
            make up-all
            ```
          </Tab>

          <Tab title="With Knowledge Base">
            Starts everything above **plus** `document-api` and `opensearch`.
            Use this if you want to upload documents and use RAG / vector search in your assistants.
            This command also builds required images in low-memory mode.

            ```bash theme={null}
            make up-all-with-knowledge
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Optional: pre-build images separately">
        If you want to pre-build before startup or use CI cache warming:

        <Tabs>
          <Tab title="Voice Only (recommended)">
            Builds all core services. Does **not** include `document-api` or `opensearch`.

            ```bash theme={null}
            make build-all
            ```
          </Tab>

          <Tab title="With Knowledge Base">
            Builds everything, including `document-api` (Python image) and pulls the OpenSearch image.
            Requires **8–16 GB RAM** due to OpenSearch.

            ```bash theme={null}
            make build-all-with-knowledge
            ```
          </Tab>
        </Tabs>

        Initial build takes 5–10 minutes depending on your network speed.
      </Step>

      <Step title="Access Dashboard">
        Open your browser:

        * **Dashboard**: [http://localhost:3000](http://localhost:3000)
        * **API Gateway**: [http://localhost:8080](http://localhost:8080)
      </Step>
    </Steps>

    ### Verify Services Are Running

    ```bash theme={null}
    make ps-all
    ```

    All containers should show `Up` status.

    ### Enabling Knowledge Base Later

    Started with Voice Only and want to add knowledge base support? No reinstall needed:

    ```bash theme={null}
    # Build + start document-api and opensearch alongside existing services
    make up-all-with-knowledge
    ```

    Your existing data (PostgreSQL, Redis) is untouched. The new services simply start alongside what's already running.

    ### View Logs

    ```bash theme={null}
    # All services
    make logs-all

    # Specific service
    make logs-web
    make logs-assistant
    make logs-db
    ```

    ### Stop Services

    ```bash theme={null}
    # Stop all services
    make down-all

    # Stop specific service
    make down-web
    ```

    ## Using Existing Infrastructure

    If you already have **PostgreSQL**, **Redis**, or **OpenSearch** running, you can skip those services.

    ### Example: Use Existing PostgreSQL

    Edit `docker-compose.yml` and comment out or remove the `postgres` service:

    ```yaml theme={null}
    # postgres:
    #   image: postgres:15
    #   ...
    ```

    Update PostgreSQL settings in `docker/web-api/web.yml`:

    ```yaml theme={null}
    postgres:
      host: host.docker.internal
      port: 5432
      db_name: web_db
      auth:
        user: your_user
        password: your_password
    ```

    ### Example: Use Existing Redis

    Comment out Redis in `docker-compose.yml`:

    ```yaml theme={null}
    # redis:
    #   image: redis:7
    #   ...
    ```

    Update Redis settings in the service YAML files:

    ```yaml theme={null}
    redis:
      host: host.docker.internal
      port: 6379
    ```

    ### Example: Use Existing OpenSearch

    OpenSearch is **only required for the knowledge base**. If you don't need knowledge base features, simply run `make up-all` (without the `with-knowledge` profile) and OpenSearch is not started at all.

    If you do need knowledge base support and want to use an existing OpenSearch instance, comment out the `opensearch` service in `docker-compose.knowledge.yml`:

    ```yaml theme={null}
    # opensearch:
    #   image: opensearchproject/opensearch:2.11
    #   ...
    ```

    Then update `docker/assistant-api/assistant.knowledge.yml`:

    ```yaml theme={null}
    opensearch:
      schema: http
      host: host.docker.internal
      port: 9200
      auth:
        user: admin
        password: admin
    ```

    And run with the knowledge profile:

    ```bash theme={null}
    make up-all-with-knowledge
    ```

    ## Next Steps

    After installation:

    1. **[Configure Services](/opensource/configuration)** - Set up API keys and integrations
    2. **[Services Overview](/opensource/services)** - Understand what each service does
    3. **[Troubleshooting](/opensource/troubleshooting)** - Fix common issues
  </Tab>

  <Tab title="Manual Setup">
    For developers who prefer not to use Docker. This requires installing each component individually.

    <Info>
      Same choice applies here: **Voice Only** (PostgreSQL + Redis only) or **With Knowledge Base** (PostgreSQL + Redis + OpenSearch + Python). If you only need voice assistants, skip the OpenSearch and Python/document-api sections below.
    </Info>

    ### Prerequisites

    <CodeGroup>
      ```bash macOS theme={null}
      # Install Homebrew first (if not installed)
      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

      # Install required tools
      brew install go@1.25 python@3.11 node@22 postgresql@15 redis opensearch

      # Verify installations
      go version      # go1.25+
      python --version # python3.11+
      node --version  # node22+
      ```

      ```bash Linux (Ubuntu/Debian) theme={null}
      # Update system
      sudo apt-get update && sudo apt-get upgrade -y

      # Install dependencies
      sudo apt-get install -y \
        curl git build-essential \
        golang-1.25 \
        python3.11 python3.11-venv python3-pip \
        nodejs npm yarn \
        postgresql postgresql-contrib \
        redis-server

      # Install OpenSearch (requires more setup)
      # See https://opensearch.org/docs/latest/install/

      # Verify installations
      go version
      python3 --version
      node --version
      psql --version
      ```

      ```bash Windows (WSL2) theme={null}
      # First enable WSL2 in PowerShell (run as admin)
      wsl --install
      wsl --set-default-version 2

      # Install Ubuntu 22.04 LTS from Microsoft Store
      # Then open Ubuntu terminal and run:
      sudo apt-get update && sudo apt-get upgrade -y
      sudo apt-get install -y \
        curl git build-essential \
        golang-1.25 \
        python3.11 python3.11-venv python3-pip \
        nodejs npm yarn \
        postgresql postgresql-contrib \
        redis-server
      ```
    </CodeGroup>

    #### PostgreSQL

    <CodeGroup>
      ```bash macOS theme={null}
      # Start PostgreSQL
      brew services start postgresql@15

      # Verify it's running
      psql --version
      ```

      ```bash Linux theme={null}
      # Start PostgreSQL
      sudo systemctl start postgresql
      sudo systemctl enable postgresql

      # Verify it's running
      sudo systemctl status postgresql
      ```

      ```bash Windows (WSL2) theme={null}
      # Start PostgreSQL
      sudo systemctl start postgresql

      # Verify it's running
      sudo systemctl status postgresql
      ```
    </CodeGroup>

    Create databases:

    ```bash theme={null}
    # Connect to PostgreSQL
    psql postgres

    # Run these SQL commands:
    CREATE USER rapida_user WITH PASSWORD 'rapida_db_password';
    CREATE DATABASE web_db OWNER rapida_user;
    CREATE DATABASE assistant_db OWNER rapida_user;
    CREATE DATABASE integration_db OWNER rapida_user;
    CREATE DATABASE endpoint_db OWNER rapida_user;
    GRANT ALL PRIVILEGES ON DATABASE web_db TO rapida_user;
    GRANT ALL PRIVILEGES ON DATABASE assistant_db TO rapida_user;
    GRANT ALL PRIVILEGES ON DATABASE integration_db TO rapida_user;
    GRANT ALL PRIVILEGES ON DATABASE endpoint_db TO rapida_user;
    \q
    ```

    #### Redis

    <CodeGroup>
      ```bash macOS theme={null}
      # Start Redis
      brew services start redis

      # Verify it's running
      redis-cli ping
      # Should return: PONG
      ```

      ```bash Linux theme={null}
      # Start Redis
      sudo systemctl start redis-server
      sudo systemctl enable redis-server

      # Verify it's running
      redis-cli ping
      ```

      ```bash Windows (WSL2) theme={null}
      # Start Redis
      sudo systemctl start redis-server

      # Verify it's running
      redis-cli ping
      ```
    </CodeGroup>

    #### OpenSearch (Optional — Knowledge Base Only)

    OpenSearch is only needed if you want to use knowledge base / RAG features. Skip this section if you only need voice assistant functionality.

    <CodeGroup>
      ```bash macOS theme={null}
      # Install OpenSearch (requires Java)
      brew tap opensearch-project/opensearch
      brew install opensearch

      # Start OpenSearch
      opensearchctl start

      # Verify it's running
      curl -s http://localhost:9200/_cluster/health | jq .
      ```

      ```bash Linux theme={null}
      # Download and install OpenSearch
      cd /opt
      sudo wget https://artifacts.opensearch.org/releases/core/opensearch/opensearch-2.11.0-linux-x64.tar.gz
      sudo tar -xzf opensearch-2.11.0-linux-x64.tar.gz
      sudo mv opensearch-2.11.0 opensearch

      # Set permissions
      sudo useradd opensearch || true
      sudo chown -R opensearch:opensearch /opt/opensearch

      # Create service file
      sudo nano /etc/systemd/system/opensearch.service

      # Add this content to opensearch.service:
      # [Unit]
      # Description=OpenSearch
      # After=network.target
      # [Service]
      # Type=simple
      # User=opensearch
      # ExecStart=/opt/opensearch/bin/opensearch
      # Restart=always
      # [Install]
      # WantedBy=multi-user.target

      # Then start:
      sudo systemctl daemon-reload
      sudo systemctl start opensearch
      sudo systemctl enable opensearch
      ```

      ```bash Windows (WSL2) theme={null}
      # Similar to Linux setup
      cd /opt
      sudo wget https://artifacts.opensearch.org/releases/core/opensearch/opensearch-2.11.0-linux-x64.tar.gz
      sudo tar -xzf opensearch-2.11.0-linux-x64.tar.gz
      sudo mv opensearch-2.11.0 opensearch
      ```
    </CodeGroup>

    #### Clone Repository

    ```bash theme={null}
    git clone https://github.com/rapidaai/voice-ai.git
    cd voice-ai
    ```

    #### Install Assistant API Dependencies

    The Assistant API requires RNNoise and Azure Speech SDK for audio processing.

    <CodeGroup>
      ```bash macOS theme={null}
      # Install RNNoise
      brew install autoconf automake libtool pkg-config
      git clone https://github.com/rapidaai/rnnoise.git
      cd rnnoise
      ./autogen.sh
      ./configure --prefix=/usr/local
      make -j$(sysctl -n hw.ncpu)
      sudo make install
      cd ..

      # Install Azure Speech SDK
      wget -O SpeechSDK-macOS.tar.gz https://aka.ms/csspeech/macosbinary
      mkdir -p ~/opt/azure-speech-sdk
      tar --strip 1 -xzf SpeechSDK-macOS.tar.gz -C ~/opt/azure-speech-sdk
      rm SpeechSDK-macOS.tar.gz

      # Add to shell profile (~/.zprofile or ~/.bash_profile)
      export LD_LIBRARY_PATH="$HOME/opt/azure-speech-sdk/lib:$LD_LIBRARY_PATH"
      export DYLD_LIBRARY_PATH="$HOME/opt/azure-speech-sdk/lib:$DYLD_LIBRARY_PATH"
      ```

      ```bash Linux (Ubuntu/Debian) theme={null}
      # Install build dependencies
      sudo apt-get install -y autoconf automake libtool pkg-config gcc g++ make

      # Install RNNoise
      git clone https://github.com/rapidaai/rnnoise.git
      cd rnnoise
      ./autogen.sh
      ./configure --prefix=/usr/local
      make -j$(nproc)
      sudo make install
      cd ..

      # Add library path to system
      echo '/usr/local/lib' | sudo tee /etc/ld.so.conf.d/rnnoise.conf
      sudo ldconfig

      # Install Azure Speech SDK
      wget -O SpeechSDK-Linux.tar.gz https://aka.ms/csspeech/linuxbinary
      sudo mkdir -p /opt/azure-speech-sdk
      sudo tar --strip 1 -xzf SpeechSDK-Linux.tar.gz -C /opt/azure-speech-sdk
      rm SpeechSDK-Linux.tar.gz

      # Add to ~/.bashrc or ~/.bash_profile
      export LD_LIBRARY_PATH="/opt/azure-speech-sdk/lib/x64:/usr/local/lib:$LD_LIBRARY_PATH"
      ```

      ```bash Windows (WSL2) theme={null}
      # Install build dependencies
      sudo apt-get install -y autoconf automake libtool pkg-config gcc g++ make

      # Install RNNoise
      git clone https://github.com/rapidaai/rnnoise.git
      cd rnnoise
      ./autogen.sh
      ./configure --prefix=/usr/local
      make -j$(nproc)
      sudo make install
      cd ..

      # Install Azure Speech SDK
      wget -O SpeechSDK-Linux.tar.gz https://aka.ms/csspeech/linuxbinary
      sudo mkdir -p /opt/azure-speech-sdk
      sudo tar --strip 1 -xzf SpeechSDK-Linux.tar.gz -C /opt/azure-speech-sdk
      rm SpeechSDK-Linux.tar.gz

      # Add to ~/.bashrc
      export LD_LIBRARY_PATH="/opt/azure-speech-sdk/lib/x64:/usr/local/lib:$LD_LIBRARY_PATH"
      ```
    </CodeGroup>

    #### Set Up Go Services

    ```bash theme={null}
    # Build all Go services
    make build-all

    # Or build individually
    make build-web
    make build-assistant
    make build-integration
    make build-endpoint
    ```

    #### Set Up Python Services (Optional — Knowledge Base Only)

    The `document-api` is only needed if you want to use the knowledge base / RAG features. Skip this step if you only need voice assistant functionality.

    ```bash theme={null}
    # Create Python virtual environment
    cd api/document-api
    python3 -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate

    # Install dependencies
    pip install -r requirements.txt

    # Note: rn_noise is included in requirements
    ```

    #### Set Up Frontend

    ```bash theme={null}
    cd ui

    # Install dependencies
    yarn install

    # Build CSS
    yarn build:css
    ```

    #### Start Services (in separate terminals)

    **Required for both modes** — start these four services first:

    <CodeGroup>
      ```bash Web Api theme={null}
      go run cmd/web/web.go
      ```

      ```bash Assistant Api theme={null}
      go run cmd/assistant/assistant.go
      ```

      ```bash Endpoint Api theme={null}
      go run cmd/endpoint/endpoint.go
      ```

      ```bash Integration Api theme={null}
      go run cmd/integration/integration.go
      ```

      ```bash Web console (UI) theme={null}
      cd ui
      yarn start:dev
      ```
    </CodeGroup>

    **Optional — only needed for knowledge base:**

    <CodeGroup>
      ```bash Document Api (optional) theme={null}
      # Requires OpenSearch running and Python venv activated
      cd api/document-api
      source venv/bin/activate
      cd ../..
      PYTHONPATH=api/document-api uvicorn app.main:app --host 0.0.0.0 --port 9010
      ```

      ```bash Celery Worker (optional) theme={null}
      # Background worker for document processing jobs
      cd api/document-api && source venv/bin/activate && cd ../..
      PYTHONPATH=api/document-api celery -A app.worker worker --loglevel=info
      ```
    </CodeGroup>

    ### Step 7: Access Dashboard

    Open your browser:

    * **Dashboard**: [http://localhost:3000](http://localhost:3000)
    * **API Gateway**: [http://localhost:8080](http://localhost:8080) (requires Nginx setup)

    ### Using Existing Infrastructure

    If you already have PostgreSQL, Redis, or OpenSearch installed:

    #### Skip PostgreSQL Installation

    Just create the databases:

    ```bash theme={null}
    psql -h localhost -U your_user -d postgres
    CREATE DATABASE web_db;
    CREATE DATABASE assistant_db;
    CREATE DATABASE integration_db;
    CREATE DATABASE endpoint_db;
    ```

    #### Skip Redis Installation

    Just update the Redis URL:

    ```bash theme={null}
    export REDIS_URL="redis://your-redis-host:6379/0"
    ```

    #### Skip OpenSearch Installation

    OpenSearch is **only required for the knowledge base**. If you don't need knowledge base features, you can skip OpenSearch entirely — just don't set `OPENSEARCH__HOST` and the assistant-api will start without knowledge base support.

    If you do need knowledge base support, update the OpenSearch env vars in your assistant-api config:

    ```bash theme={null}
    export OPENSEARCH__SCHEMA=http
    export OPENSEARCH__HOST=your-opensearch-host
    export OPENSEARCH__PORT=9200
    ```

    ## Troubleshooting

    ### Services Won't Start

    1. Check if ports are available:

    ```bash theme={null}
    lsof -i :9001  # For web-api
    lsof -i :5432  # For PostgreSQL
    ```

    2. Check PostgreSQL logs:

    ```bash theme={null}
    # macOS
    tail -f /usr/local/var/log/postgres.log

    # Linux
    sudo journalctl -u postgresql -f
    ```

    ### Connection Issues

    1. Verify PostgreSQL is running:

    ```bash theme={null}
    psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"
    ```

    2. Verify Redis is running:

    ```bash theme={null}
    redis-cli ping
    ```

    3. Verify OpenSearch is running:

    ```bash theme={null}
    curl -s http://localhost:9200/_cluster/health
    ```

    ## Next Steps

    After installation:

    1. **[Configure Services](/opensource/configuration)** - Set up API keys and integrations
    2. **[Services Overview](/opensource/services)** - Understand what each service does
    3. **[Troubleshooting](/opensource/troubleshooting)** - Fix common issues
  </Tab>
</Tabs>


# Self-Hosting Rapida
Source: https://doc.rapida.ai/opensource/overview

Run the full Rapida Voice AI platform on your own infrastructure. Docker Compose gets agencies and enterprise teams to a working deployment quickly while keeping control of data, credentials, and runtime boundaries.

## Choose your setup

Rapida supports two self-hosted deployment modes. Pick the one that matches how much retrieval and infrastructure footprint you need before you start.

<Tabs>
  <Tab title="Voice Assistant Only (Recommended)">
    **Best for most users.** Build and run AI voice assistants — inbound/outbound calls, real-time STT/LLM/TTS, webhooks, and telephony integrations.

    No OpenSearch or Python services required. Lower RAM, simpler setup, faster to get started.

    **Services started:** web-api · assistant-api · integration-api · endpoint-api · UI · PostgreSQL · Redis · Nginx

    **Services skipped:** document-api · OpenSearch

    **RAM needed:** 4 GB minimum

    ```bash theme={null}
    # Build images
    make build-all

    # Start all services
    make up-all
    ```

    That's it — open [http://localhost:3000](http://localhost:3000) and create your first assistant in an environment you control.
  </Tab>

  <Tab title="Voice Assistant + Knowledge Base">
    **Add this when you need RAG.** Everything in Voice Only, plus the ability to upload documents (PDF, DOCX, CSV, etc.) and have the assistant search and answer questions from your own content using vector embeddings.

    Requires OpenSearch (memory-intensive) and the Python `document-api` service.

    **Extra services added:** document-api · OpenSearch

    **RAM needed:** 8–16 GB (OpenSearch alone uses 4–8 GB)

    ```bash theme={null}
    # Build images (includes document-api Python image)
    make build-all-with-knowledge

    # Start all services including document-api and opensearch
    make up-all-with-knowledge
    ```

    After starting, go to **Knowledge** in the dashboard to create a knowledge base and upload documents.
  </Tab>
</Tabs>

<Info>
  **Not sure which to pick?** Start with Voice Only (`make up-all`). You can add the knowledge base at any time later — just run `make up-all-with-knowledge`. No existing data is lost and you keep the same deployment model.
</Info>

***

## What is the knowledge base?

The knowledge base lets your voice assistant answer questions grounded in your own documents. When a caller asks something, the assistant searches your uploaded content and injects the most relevant passages into the LLM prompt before generating a response. This is called Retrieval-Augmented Generation (RAG).

| Feature                              | Without knowledge base | With knowledge base |
| ------------------------------------ | ---------------------- | ------------------- |
| Voice calls (STT → LLM → TTS)        | ✅                      | ✅                   |
| Inbound / outbound telephony         | ✅                      | ✅                   |
| Webhooks & callbacks                 | ✅                      | ✅                   |
| LLM provider integrations            | ✅                      | ✅                   |
| Upload documents (PDF, DOCX, CSV…)   | ✗                      | ✅                   |
| Answer questions from your documents | ✗                      | ✅                   |
| Semantic / vector search             | ✗                      | ✅                   |
| OpenSearch required                  | ✗                      | ✅                   |
| RAM requirement                      | \~4 GB                 | \~8–16 GB           |

***

## What you are deploying

Rapida is a microservices platform. Self-hosting means running all services on your own infrastructure so you control the runtime boundary, network path, and operational model.

| Service           | Port        | Role                                                                          |
| ----------------- | ----------- | ----------------------------------------------------------------------------- |
| `nginx`           | 8080        | Reverse proxy, WebSocket upgrade, SSL/TLS termination                         |
| `web-api`         | 9001        | Auth, organizations, credential vault, gRPC proxy                             |
| `assistant-api`   | 9007 · 4573 | Voice orchestration, STT/LLM/TTS pipeline, telephony                          |
| `integration-api` | 9004        | LLM, STT, TTS provider integrations                                           |
| `endpoint-api`    | 9005        | Webhook delivery and event routing                                            |
| `document-api`    | 9010        | Document ingestion, embeddings, RAG search *(optional — knowledge base only)* |
| `ui`              | 3000        | React dashboard                                                               |
| `postgres`        | 5432        | Relational data (4 databases)                                                 |
| `redis`           | 6379        | Cache, sessions, job queue                                                    |
| `opensearch`      | 9200        | Conversation search, document indexing *(optional — knowledge base only)*     |

<Info>
  The recommended path for self-hosting is Docker Compose. All services, infrastructure, and Nginx are wired together in `docker-compose.yml`. No manual network or volume configuration is needed.
</Info>

***

## Prerequisites

| Requirement    | Version                      | Notes                                                                                   |
| -------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| Docker Engine  | 20.10+                       | [Install Docker](https://docs.docker.com/get-docker/)                                   |
| Docker Compose | v2.0+                        | Included with Docker Desktop                                                            |
| RAM            | 4 GB minimum                 | 8 GB recommended; 16 GB if running with knowledge base (OpenSearch is memory-intensive) |
| Disk           | 10 GB free                   | For images, volumes, and uploaded assets                                                |
| OS             | macOS · Linux · Windows WSL2 |                                                                                         |

***

## Quickstart

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/rapidaai/voice-ai.git
    cd voice-ai
    ```
  </Step>

  <Step title="Create data directories">
    ```bash theme={null}
    make setup-local
    ```

    Creates `~/rapida-data/assets/{db,redis,opensearch}` with the correct ownership for Docker volume mounts. The `opensearch` directory is only used when running with the knowledge base profile.

    <Note>
      **macOS users:** `make setup-local` uses `setfacl`, which is a Linux utility. If the command fails, create the directories manually:

      ```bash theme={null}
      mkdir -p ~/rapida-data/assets/opensearch ~/rapida-data/assets/db ~/rapida-data/assets/redis
      sudo chown -R 1000:1000 ~/rapida-data/assets/opensearch
      ```
    </Note>
  </Step>

  <Step title="Configure YAML files">
    Each service reads from a YAML config file in `docker/<service>/`. The defaults work for a local deployment with no external providers. You do not need any API keys to start the platform.

    ```
    docker/web-api/web.yml
    docker/assistant-api/assistant.yml
    docker/integration-api/integration.yml
    docker/endpoint-api/endpoint.yml
    docker/document-api/config.yaml
    ```

    <Warning>
      Before going to production, change `secret: "rpd_pks"` to a strong random value in every service config. All services share the same secret for JWT signing. Generate one with `openssl rand -hex 32`.
    </Warning>
  </Step>

  <Step title="Build all service images">
    ```bash theme={null}
    # Without knowledge base (recommended for most users)
    make build-all

    # With knowledge base (includes document-api and opensearch)
    make build-all-with-knowledge
    ```

    Builds Docker images for all Go services. Initial build takes 5–10 minutes depending on your network.
  </Step>

  <Step title="Start all services">
    ```bash theme={null}
    # Without knowledge base — voice assistants only
    make up-all

    # With knowledge base — includes document-api and opensearch
    make up-all-with-knowledge
    ```

    <Note>
      The default `make up-all` starts all core services (web-api, assistant-api, integration-api, endpoint-api, UI, PostgreSQL, Redis, Nginx). `document-api` and `opensearch` are **optional** and only started with the `with-knowledge` variant. You can always add knowledge base support later by running `make up-all-with-knowledge`.
    </Note>
  </Step>

  <Step title="Verify all services are healthy">
    ```bash theme={null}
    make status
    ```

    All containers should show `Up` or `Up (healthy)`. If any container is in `Exited` state, check its logs:

    ```bash theme={null}
    make logs-all
    ```
  </Step>

  <Step title="Open the dashboard">
    Navigate to **[http://localhost:3000](http://localhost:3000)** in your browser. You should see the Rapida login page.

    The Nginx gateway is accessible at **[http://localhost:8080](http://localhost:8080)**.
  </Step>
</Steps>

***

## Service Endpoints

| Service         | URL                                            | Health Check           | Required                       |
| --------------- | ---------------------------------------------- | ---------------------- | ------------------------------ |
| Dashboard       | [http://localhost:3000](http://localhost:3000) | —                      | Yes                            |
| Nginx Gateway   | [http://localhost:8080](http://localhost:8080) | —                      | Yes                            |
| Web API         | [http://localhost:9001](http://localhost:9001) | `GET /readiness/`      | Yes                            |
| Assistant API   | [http://localhost:9007](http://localhost:9007) | `GET /readiness/`      | Yes                            |
| Integration API | [http://localhost:9004](http://localhost:9004) | `GET /readiness/`      | Yes                            |
| Endpoint API    | [http://localhost:9005](http://localhost:9005) | `GET /readiness/`      | Yes                            |
| Document API    | [http://localhost:9010](http://localhost:9010) | `GET /readiness/`      | Optional (knowledge base only) |
| OpenSearch      | [http://localhost:9200](http://localhost:9200) | `GET /_cluster/health` | Optional (knowledge base only) |

```bash theme={null}
# Verify a specific service
curl http://localhost:9001/readiness/
```

***

## Working with Individual Services

### Start / stop specific services

```bash theme={null}
# Infrastructure only (postgres, redis, opensearch)
make deps

# Individual services
make up-web
make up-assistant
make up-integration
make up-endpoint
make up-document
make up-ui
```

### Logs

```bash theme={null}
make logs-all           # All services
make logs-web           # web-api only
make logs-assistant     # assistant-api only
make logs-integration   # integration-api only
make logs-endpoint      # endpoint-api only
make logs-document      # document-api only
```

### Rebuild after code changes

```bash theme={null}
make rebuild-web        # Rebuild web-api (no cache)
make rebuild-assistant  # Rebuild assistant-api (no cache)
make rebuild-all        # Rebuild all services (no cache)
```

### Shell access

```bash theme={null}
make shell-web          # Shell into web-api container
make shell-assistant    # Shell into assistant-api container
make shell-db           # psql shell → PostgreSQL (rapida_user / web_db)
```

***

## Connecting Your First Provider

The platform runs without any external provider keys. To place a voice call, you need to add at least one LLM, one STT, and one TTS provider credential through the dashboard.

<Steps>
  <Step title="Open the dashboard">
    Navigate to [http://localhost:3000](http://localhost:3000) and create an account.
  </Step>

  <Step title="Create an organization and project">
    Every resource in Rapida is scoped to an organization and project.
  </Step>

  <Step title="Add provider credentials">
    Go to **Settings → Integrations** and add API keys for your LLM (e.g., OpenAI), STT (e.g., Deepgram), and TTS (e.g., ElevenLabs) providers.

    Credentials are encrypted with AES-256-GCM before storage. See [Integration API](/opensource/services/integration-api) for details.
  </Step>

  <Step title="Create an assistant">
    Go to **Assistants → New Assistant** and configure the system prompt, LLM, STT, TTS, and (optionally) a knowledge base.
  </Step>

  <Step title="Test the call">
    Use the built-in call tester in the dashboard or connect via the [rapida-react SDK](https://github.com/rapidaai/rapida-react).
  </Step>
</Steps>

***

## Make Command Reference

| Command                           | Description                                              |
| --------------------------------- | -------------------------------------------------------- |
| `make setup-local`                | Create data directories with correct permissions         |
| `make build-all`                  | Build all Docker images (without knowledge base)         |
| `make build-all-with-knowledge`   | Build all Docker images including document-api           |
| `make rebuild-all`                | Rebuild all images (no cache, without knowledge base)    |
| `make rebuild-all-with-knowledge` | Rebuild all images including document-api (no cache)     |
| `make rebuild-<service>`          | Rebuild a single service (no cache)                      |
| `make up-all`                     | Start all services (without knowledge base)              |
| `make up-all-with-knowledge`      | Start all services including document-api and opensearch |
| `make down-all`                   | Stop all services                                        |
| `make restart-all`                | Restart all services                                     |
| `make deps`                       | Start infrastructure only (postgres, redis)              |
| `make status`                     | Show container status and port mappings                  |
| `make logs-all`                   | Tail all service logs                                    |
| `make logs-<service>`             | Tail logs for a specific service                         |
| `make shell-<service>`            | Open a shell inside a service container                  |
| `make shell-db`                   | Open psql shell in the PostgreSQL container              |
| `make clean`                      | Remove all containers, volumes, and images               |
| `make ps-all`                     | List container status                                    |

***

## Stopping and Resetting

```bash theme={null}
# Stop all services (preserve volumes)
make down-all

# Full reset — removes containers, volumes, and images
make clean
```

<Warning>
  `make clean` deletes all Docker volumes, including the PostgreSQL data directory and (if used) the OpenSearch data directory. All database content and indexed documents will be lost.
</Warning>

***

## Next Steps

<CardGroup>
  <Card title="Architecture" icon="network" href="/opensource/architecture">
    System topology, service communication, and data flow diagrams.
  </Card>

  <Card title="Configuration Reference" icon="sliders" href="/opensource/configuration">
    Complete environment variable reference for all services.
  </Card>

  <Card title="Services Overview" icon="server" href="/opensource/services">
    Per-service documentation — components, routing, configuration.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/opensource/troubleshooting">
    Common issues and solutions for Docker and local setup.
  </Card>
</CardGroup>


# Assistant API — Configuration
Source: https://doc.rapida.ai/opensource/services/assistant-api/configuration

Complete environment variable reference for the assistant-api service.

## Configuration File

Edit `docker/assistant-api/.assistant.env` before starting the service.

For local development (without Docker), export the variables and override the Docker hostnames shown in the table below.

***

## Required Variables

| Variable                   | Default                | Description                                                                 |
| -------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `SECRET`                   | `rpd_pks`              | JWT signing secret — must be identical across all services                  |
| `POSTGRES__HOST`           | `postgres`             | PostgreSQL host                                                             |
| `POSTGRES__DB_NAME`        | `assistant_db`         | Database name                                                               |
| `POSTGRES__AUTH__USER`     | `rapida_user`          | Database user                                                               |
| `POSTGRES__AUTH__PASSWORD` | `rapida_db_password`   | Database password                                                           |
| `REDIS__HOST`              | `redis`                | Redis host                                                                  |
| `OPENSEARCH__HOST`         | *(empty)*              | OpenSearch host — **optional**, leave empty to disable knowledge base       |
| `INTEGRATION_HOST`         | `integration-api:9004` | integration-api gRPC address                                                |
| `ENDPOINT_HOST`            | `endpoint-api:9005`    | endpoint-api gRPC address                                                   |
| `WEB_HOST`                 | `web-api:9001`         | web-api gRPC address                                                        |
| `DOCUMENT_HOST`            | *(empty)*              | document-api HTTP address — **optional**, only needed for knowledge base    |
| `PUBLIC_ASSISTANT_HOST`    | —                      | **Publicly reachable hostname** for telephony callbacks and WebSocket media |

<Warning>
  `PUBLIC_ASSISTANT_HOST` must resolve from the public internet. Twilio, Vonage, and Exotel connect WebSocket media streams to `wss://PUBLIC_ASSISTANT_HOST/v1/talk/{provider}/ctx/{contextId}`. For local testing, use an ngrok tunnel and set this to your ngrok hostname (e.g. `abc123.ngrok.io`).
</Warning>

***

## Service Identity

| Variable       | Default        | Description                              |
| -------------- | -------------- | ---------------------------------------- |
| `SERVICE_NAME` | `workflow-api` | Internal service name label              |
| `HOST`         | `0.0.0.0`      | Bind address                             |
| `PORT`         | `9007`         | HTTP / gRPC / WebSocket port (cmux)      |
| `LOG_LEVEL`    | `debug`        | `debug` · `info` · `warn` · `error`      |
| `ENV`          | `development`  | `development` · `staging` · `production` |

***

## PostgreSQL

| Variable                              | Default              | Description                            |
| ------------------------------------- | -------------------- | -------------------------------------- |
| `POSTGRES__HOST`                      | `postgres`           | Host (`localhost` for local dev)       |
| `POSTGRES__PORT`                      | `5432`               | Port                                   |
| `POSTGRES__DB_NAME`                   | `assistant_db`       | Database name                          |
| `POSTGRES__AUTH__USER`                | `rapida_user`        | User                                   |
| `POSTGRES__AUTH__PASSWORD`            | `rapida_db_password` | Password                               |
| `POSTGRES__MAX_OPEN_CONNECTION`       | `50`                 | Connection pool size                   |
| `POSTGRES__MAX_IDEAL_CONNECTION`      | `25`                 | Idle connections                       |
| `POSTGRES__SSL_MODE`                  | `disable`            | `disable` · `require` · `verify-full`  |
| `POSTGRES__SLC_CACHE__HOST`           | `redis`              | Redis host for second-level GORM cache |
| `POSTGRES__SLC_CACHE__PORT`           | `6379`               | Redis port for GORM cache              |
| `POSTGRES__SLC_CACHE__DB`             | `1`                  | Redis DB index for GORM cache          |
| `POSTGRES__SLC_CACHE__MAX_CONNECTION` | `10`                 | Redis pool size                        |

***

## Redis

| Variable                | Default | Description                            |
| ----------------------- | ------- | -------------------------------------- |
| `REDIS__HOST`           | `redis` | Redis host (`localhost` for local dev) |
| `REDIS__PORT`           | `6379`  | Redis port                             |
| `REDIS__MAX_CONNECTION` | `10`    | Connection pool size                   |
| `REDIS__MAX_DB`         | `0`     | Redis DB index                         |

***

## OpenSearch (Optional — Knowledge Base Only)

OpenSearch is only needed for knowledge base / RAG features. If `OPENSEARCH__HOST` is left empty (the default), the assistant-api starts without knowledge base support and skips the OpenSearch connection entirely.

| Variable                     | Default   | Description                                             |
| ---------------------------- | --------- | ------------------------------------------------------- |
| `OPENSEARCH__SCHEMA`         | `http`    | `http` · `https`                                        |
| `OPENSEARCH__HOST`           | *(empty)* | OpenSearch host — leave empty to disable knowledge base |
| `OPENSEARCH__PORT`           | `9200`    | OpenSearch port                                         |
| `OPENSEARCH__MAX_RETRIES`    | `3`       | Request retry count                                     |
| `OPENSEARCH__MAX_CONNECTION` | `10`      | Connection pool size                                    |

***

## Asset Storage

| Variable                           | Default                                             | Description                          |
| ---------------------------------- | --------------------------------------------------- | ------------------------------------ |
| `ASSET_STORE__STORAGE_TYPE`        | `local`                                             | `local` · `s3` · `azure`             |
| `ASSET_STORE__STORAGE_PATH_PREFIX` | `/app/rapida-data/assets/workflow`                  | Path for local storage               |
| `ASSET_STORE__PUBLIC_URL_PREFIX`   | `http://localhost:8080/rapida-data/assets/workflow` | Public URL for serving stored assets |

***

## Telemetry (Optional)

`assistant-api` supports an optional environment-configured default telemetry exporter.

Set exporter type:

| Variable          | Default   | Description                                                                                                  |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `TELEMETRY__TYPE` | *(empty)* | `otlp_http` · `otlp_grpc` · `xray` · `google_trace` · `azure_monitor` · `datadog` · `opensearch` · `logging` |

Provider-specific keys:

### OTLP HTTP

| Variable                         | Description                          |
| -------------------------------- | ------------------------------------ |
| `TELEMETRY__OTLP_HTTP__ENDPOINT` | OTLP endpoint                        |
| `TELEMETRY__OTLP_HTTP__PROTOCOL` | `http/protobuf` or `grpc`            |
| `TELEMETRY__OTLP_HTTP__HEADERS`  | Comma-separated headers (`A=B, C=D`) |
| `TELEMETRY__OTLP_HTTP__INSECURE` | `true`/`false`                       |

### OTLP gRPC

| Variable                         | Description             |
| -------------------------------- | ----------------------- |
| `TELEMETRY__OTLP_GRPC__ENDPOINT` | OTLP endpoint           |
| `TELEMETRY__OTLP_GRPC__PROTOCOL` | Usually `grpc`          |
| `TELEMETRY__OTLP_GRPC__HEADERS`  | Comma-separated headers |
| `TELEMETRY__OTLP_GRPC__INSECURE` | `true`/`false`          |

### Datadog

| Variable                       | Description                 |
| ------------------------------ | --------------------------- |
| `TELEMETRY__DATADOG__ENDPOINT` | Datadog OTLP/agent endpoint |
| `TELEMETRY__DATADOG__PROTOCOL` | Protocol override           |
| `TELEMETRY__DATADOG__HEADERS`  | Additional headers          |
| `TELEMETRY__DATADOG__API_KEY`  | Datadog API key             |
| `TELEMETRY__DATADOG__INSECURE` | `true`/`false`              |

### AWS X-Ray

| Variable                    | Description        |
| --------------------------- | ------------------ |
| `TELEMETRY__XRAY__ENDPOINT` | ADOT/OTLP endpoint |
| `TELEMETRY__XRAY__PROTOCOL` | Protocol override  |
| `TELEMETRY__XRAY__REGION`   | AWS region         |
| `TELEMETRY__XRAY__INSECURE` | `true`/`false`     |

### Google Trace

| Variable                                | Description        |
| --------------------------------------- | ------------------ |
| `TELEMETRY__GOOGLE_TRACE__ENDPOINT`     | Trace endpoint     |
| `TELEMETRY__GOOGLE_TRACE__HEADERS`      | Additional headers |
| `TELEMETRY__GOOGLE_TRACE__API_KEY`      | API key            |
| `TELEMETRY__GOOGLE_TRACE__ACCESS_TOKEN` | OAuth bearer token |
| `TELEMETRY__GOOGLE_TRACE__INSECURE`     | `true`/`false`     |

### Azure Monitor

| Variable                             | Description                 |
| ------------------------------------ | --------------------------- |
| `TELEMETRY__AZURE_MONITOR__ENDPOINT` | Azure Monitor endpoint      |
| `TELEMETRY__AZURE_MONITOR__HEADERS`  | Additional headers          |
| `TELEMETRY__AZURE_MONITOR__API_KEY`  | API key/instrumentation key |
| `TELEMETRY__AZURE_MONITOR__INSECURE` | `true`/`false`              |

### OpenSearch / Logging

| Variable                              | Description           |
| ------------------------------------- | --------------------- |
| `TELEMETRY__OPENSEARCH__INDEX_PREFIX` | Optional index prefix |
| `TELEMETRY__LOGGING__*`               | No options required   |

***

## Asterisk AudioSocket

The AudioSocket server binds on a separate TCP port. Asterisk dials into this port directly.

| Variable            | Default   | Description                                 |
| ------------------- | --------- | ------------------------------------------- |
| `AUDIOSOCKET__HOST` | `0.0.0.0` | Bind address for the AudioSocket TCP server |
| `AUDIOSOCKET__PORT` | `4573`    | TCP port for AudioSocket connections        |

**Asterisk dialplan usage:**

```
same = n,AudioSocket(${RAPIDA_CONTEXT_ID},assistant-api-host:4573)
```

***

## SIP Server

The built-in SIP server handles direct SIP INVITE connections and Asterisk SIP trunk connections.

| Variable                    | Default   | Description                                                                               |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------- |
| `SIP__SERVER`               | `0.0.0.0` | Bind address for SIP                                                                      |
| `SIP__EXTERNAL_IP`          | `0.0.0.0` | **Public IP** advertised in SDP and SIP Contact headers — must be your server's public IP |
| `SIP__PORT`                 | `5090`    | SIP signalling port (UDP)                                                                 |
| `SIP__TRANSPORT`            | `udp`     | `udp` · `tcp`                                                                             |
| `SIP__RTP_PORT_RANGE_START` | `10000`   | RTP media port range start                                                                |
| `SIP__RTP_PORT_RANGE_END`   | `20000`   | RTP media port range end                                                                  |

<Warning>
  Set `SIP__EXTERNAL_IP` to your server's public IP address. If this is set to `0.0.0.0`, SDP answers will advertise the wrong address and media will not flow for callers outside the local network.
</Warning>

**SIP connection string:**

```
sip:agent-{assistantID}@{SIP__EXTERNAL_IP}:{SIP__PORT}
sip:did-{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}
sip:{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}
```

***

## Full Environment File

```env theme={null}
# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=workflow-api
HOST=0.0.0.0
PORT=9007
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── Asset storage ─────────────────────────────────────────────────
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/workflow
ASSET_STORE__PUBLIC_URL_PREFIX=http://localhost:8080/rapida-data/assets/workflow

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=assistant_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432
POSTGRES__MAX_OPEN_CONNECTION=50
POSTGRES__MAX_IDEAL_CONNECTION=25
POSTGRES__SSL_MODE=disable
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__MAX_CONNECTION=10
POSTGRES__SLC_CACHE__DB=1

# ── Redis ─────────────────────────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=10
REDIS__MAX_DB=0

# ── OpenSearch (optional — remove or leave empty to disable knowledge base) ──
# OPENSEARCH__SCHEMA=http
# OPENSEARCH__HOST=opensearch
# OPENSEARCH__PORT=9200
# OPENSEARCH__MAX_RETRIES=3
# OPENSEARCH__MAX_CONNECTION=10

# ── Internal service addresses ────────────────────────────────────
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
# DOCUMENT_HOST=http://document-api:9010   # optional — only needed for knowledge base
UI_HOST=https://localhost:3000

# ── Public hostname (required for telephony) ──────────────────────
PUBLIC_ASSISTANT_HOST=your-public-hostname.example.com

# ── Asterisk AudioSocket ──────────────────────────────────────────
AUDIOSOCKET__HOST=0.0.0.0
AUDIOSOCKET__PORT=4573

# ── SIP Server ────────────────────────────────────────────────────
SIP__SERVER=0.0.0.0
SIP__EXTERNAL_IP=0.0.0.0
SIP__PORT=5090
SIP__TRANSPORT=udp
SIP__RTP_PORT_RANGE_START=10000
SIP__RTP_PORT_RANGE_END=20000
```

***

## Local Development Overrides

When running from source, override Docker hostnames:

```bash theme={null}
export $(grep -v '^#' docker/assistant-api/.assistant.env | xargs)
export POSTGRES__HOST=localhost
export REDIS__HOST=localhost
export INTEGRATION_HOST=localhost:9004
export ENDPOINT_HOST=localhost:9005
export WEB_HOST=localhost:9001

# Optional: only needed for knowledge base features
# export OPENSEARCH__HOST=localhost
# export DOCUMENT_HOST=http://localhost:9010

go run cmd/assistant/assistant.go
```

***

## Next Steps

<CardGroup>
  <Card title="STT / TTS Providers" icon="mic" href="/opensource/services/assistant-api/stt-tts">
    Configure and add speech recognition and synthesis providers.
  </Card>

  <Card title="Telephony" icon="phone" href="/opensource/services/assistant-api/telephony">
    Twilio, Asterisk, SIP, and other telephony provider setup.
  </Card>
</CardGroup>


# LiveKit Turn Detector EOS
Source: https://doc.rapida.ai/opensource/services/assistant-api/eos/livekit

Configure LiveKit Turn Detector end-of-speech detection in assistant-api.

The [LiveKit Turn Detector](https://github.com/livekit/turn-detector) uses a language model to predict turn completion from transcribed text combined with conversation history. It understands that incomplete sentences, addresses, and phone numbers are not finished turns — even when the caller pauses.

**Provider identifier:** `livekit_eos`

***

## Source Location

```
api/assistant-api/internal/end_of_speech/internal/livekit/
├── livekit_end_of_speech.go   # Main implementation
├── turn_detector.go           # ONNX inference + tokenizer
├── chat_template.go           # Conversation history formatting
├── models/
│   ├── model_q8.onnx                  # English model (~66 MB, downloaded at build)
│   ├── model_q8_multilingual.onnx     # Multilingual model (~378 MB, downloaded at build)
│   └── tokenizer.json                 # Shared tokenizer
```

***

## How It Works

1. Final `SpeechToTextPacket` transcripts are accumulated into the current user turn
2. The model builds a chat template from conversation history (user + assistant turns) + current text
3. The tokenizer encodes the text and the ONNX model predicts an end-of-utterance probability
4. If `probability >= threshold` → timer set to `quick_timeout`
5. If `probability < threshold` → timer set to `silence_timeout`
6. `LLMResponseDonePacket` events record assistant turns in conversation history for context-aware predictions
7. Interim transcripts reset the timer to `fallback_timeout`

```
History: [user: "I need to book a flight", assistant: "Sure, what's your destination?"]
Current: "I'd like to go to"
Model: P(complete) = 0.005 → still speaking → timer = 1500ms

Current: "I'd like to go to London please"
Model: P(complete) = 0.042 → done → timer = 250ms (quick)
```

***

## Parameters

| Option Key                         | Default   | Range                | Description                                             |
| ---------------------------------- | --------- | -------------------- | ------------------------------------------------------- |
| `microphone.eos.model`             | `en`      | `en`, `multilingual` | Model variant                                           |
| `microphone.eos.threshold`         | `0.0289`  | 0.001–0.1            | Turn completion probability threshold                   |
| `microphone.eos.quick_timeout`     | `250 ms`  | 50–500 ms            | Silence buffer when model says "done"                   |
| `microphone.eos.silence_timeout`   | `3000 ms` | 500–5000 ms          | Max silence when model says "still speaking"            |
| `microphone.eos.timeout`           | `500 ms`  | 300–2000 ms          | Fallback for interim transcripts and inference failures |
| `microphone.eos.max_history_turns` | `6`       | 1–20                 | Conversation history turns used for context             |

<Warning>
  The threshold range (0.001–0.1) is very different from Pipecat's (0.1–0.9). These are different models with different probability distributions. Do not copy threshold values between providers.
</Warning>

### Model Variants

| Variant      | Identifier     | Size   | Languages                                              |
| ------------ | -------------- | ------ | ------------------------------------------------------ |
| English      | `en`           | 66 MB  | English (optimized)                                    |
| Multilingual | `multilingual` | 378 MB | zh, de, nl, en, pt, es, fr, it, ja, ko, ru, tr, id, hi |

***

## Model Setup

### Docker

All models are downloaded from Hugging Face and patched during the Docker build. No manual action required.

```env theme={null}
# Set automatically in the Dockerfile
LIVEKIT_TURN_MODEL_PATH=./models/livekit_turn/model_q8.onnx
LIVEKIT_TURN_MULTI_MODEL_PATH=./models/livekit_turn/model_q8_multilingual.onnx
LIVEKIT_TURN_TOKENIZER_PATH=./models/livekit_turn/tokenizer.json
```

### From Source

Download the models manually:

```bash theme={null}
mkdir -p api/assistant-api/internal/end_of_speech/internal/livekit/models

# English model (required)
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8.onnx \
    "https://huggingface.co/livekit/turn-detector/resolve/v1.2.2-en/onnx/model_q8.onnx"

# Tokenizer (required)
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/tokenizer.json \
    "https://huggingface.co/livekit/turn-detector/resolve/v1.2.2-en/tokenizer.json"

# Multilingual model (optional — only if using multilingual mode)
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8_multilingual.onnx \
    "https://huggingface.co/livekit/turn-detector/resolve/v0.4.1-intl/onnx/model_q8.onnx"
```

If you encounter ONNX opset errors, patch the models:

```bash theme={null}
pip install onnx
python3 -c "
import onnx
for path in [
    'api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8.onnx',
    'api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8_multilingual.onnx',
]:
    try:
        m = onnx.load(path)
        used = {n.domain for n in m.graph.node}
        keep = [o for o in m.opset_import if o.domain == '' or o.domain in used]
        del m.opset_import[:]
        m.opset_import.extend(keep)
        onnx.save(m, path)
        print(f'Patched {path}')
    except FileNotFoundError:
        pass
"
```

To override paths:

```bash theme={null}
export LIVEKIT_TURN_MODEL_PATH=/path/to/model_q8.onnx
export LIVEKIT_TURN_MULTI_MODEL_PATH=/path/to/model_q8_multilingual.onnx
export LIVEKIT_TURN_TOKENIZER_PATH=/path/to/tokenizer.json
```

Requires ONNX Runtime (`libonnxruntime`) — same dependency as Silero/FireRed VAD.


# End of Speech Detection — Overview
Source: https://doc.rapida.ai/opensource/services/assistant-api/eos/overview

EOS interface, factory function, providers, and model setup in assistant-api.

End of Speech (EOS) detection determines when a caller has finished their turn and the assistant should begin responding. It runs downstream of VAD and STT — it receives speech activity signals, interim transcripts, and final transcripts, then decides when to fire the `EndOfSpeechPacket` that triggers LLM inference.

***

## EOS Interface

Every provider implements the `EndOfSpeech` interface:

```go theme={null}
// api/assistant-api/internal/type/end_of_speech.go
type EndOfSpeech interface {
    Name() string
    Analyze(ctx context.Context, pkt Packet) error
    Close() error
}
```

The `Analyze` method receives multiple packet types:

| Packet Type                      | What it signals                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------ |
| `SpeechToTextPacket` (interim)   | Caller is still speaking — reset the silence timer                                   |
| `SpeechToTextPacket` (final)     | A complete transcript segment — accumulate text, run model inference (if applicable) |
| `InterruptionPacket` (VAD start) | Speech onset detected — block EOS completion while VAD is active                     |
| `InterruptionPacket` (VAD end)   | Speech offset detected — flush pending EOS if transcript exists                      |
| `UserTextPacket`                 | Text input from web/chat — fire immediately (no silence detection needed)            |
| `LLMResponseDonePacket`          | Assistant finished responding — recorded in conversation history (LiveKit only)      |

***

## Factory Function

```go theme={null}
// api/assistant-api/internal/end_of_speech/end_of_speech.go
func GetEndOfSpeech(ctx, logger, onCallback, opts) (EndOfSpeech, error)
```

The factory reads `microphone.eos.provider` from the assistant's audio options. If no provider is set, **Silence-Based EOS** is used as the default.

***

## Provider Identifiers

| Identifier               | Provider              | Model                                                                               | Download Required     |
| ------------------------ | --------------------- | ----------------------------------------------------------------------------------- | --------------------- |
| `silence_based_eos`      | Silence-Based         | None                                                                                | No                    |
| `pipecat_smart_turn_eos` | Pipecat Smart Turn    | `smart-turn-v3.2-cpu.onnx` (\~8 MB)                                                 | Yes (at Docker build) |
| `livekit_eos`            | LiveKit Turn Detector | `model_q8.onnx` (66 MB) or `model_q8_multilingual.onnx` (378 MB) + `tokenizer.json` | Yes (at Docker build) |

***

## Model Files

Silence-Based EOS needs no model. Pipecat and LiveKit models are **downloaded from Hugging Face during the Docker build** and bundled into the runtime image.

### Docker

The Dockerfile handles all model downloads automatically:

```env theme={null}
# Set automatically in the Dockerfile — no manual config needed
LIVEKIT_TURN_MODEL_PATH=./models/livekit_turn/model_q8.onnx
LIVEKIT_TURN_MULTI_MODEL_PATH=./models/livekit_turn/model_q8_multilingual.onnx
LIVEKIT_TURN_TOKENIZER_PATH=./models/livekit_turn/tokenizer.json
PIPECAT_TURN_MODEL_PATH=./models/pipecat_turn/smart-turn-v3.2-cpu.onnx
```

### From Source

When running from source, models must be downloaded manually into the correct directories. The providers resolve paths relative to their Go package directory using `runtime.Caller`.

**Pipecat Smart Turn:**

```bash theme={null}
mkdir -p api/assistant-api/internal/end_of_speech/internal/pipecat/models

curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/pipecat/models/smart-turn-v3.2-cpu.onnx \
    "https://huggingface.co/pipecat-ai/smart-turn-v3/resolve/main/smart-turn-v3.2-cpu.onnx"
```

**LiveKit Turn Detector:**

```bash theme={null}
mkdir -p api/assistant-api/internal/end_of_speech/internal/livekit/models

# English model (66 MB)
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8.onnx \
    "https://huggingface.co/livekit/turn-detector/resolve/v1.2.2-en/onnx/model_q8.onnx"

# Multilingual model (378 MB) — only needed if using multilingual mode
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/model_q8_multilingual.onnx \
    "https://huggingface.co/livekit/turn-detector/resolve/v0.4.1-intl/onnx/model_q8.onnx"

# Tokenizer (shared by both models)
curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/livekit/models/tokenizer.json \
    "https://huggingface.co/livekit/turn-detector/resolve/v1.2.2-en/tokenizer.json"
```

<Warning>
  The LiveKit and Pipecat ONNX models may need opset patching for ONNX Runtime compatibility. The Dockerfile handles this automatically with a Python `onnx` script. If you encounter opset errors during local development, install the `onnx` Python package and run the patching commands from the Dockerfile.
</Warning>

To override model paths, set environment variables:

```bash theme={null}
export PIPECAT_TURN_MODEL_PATH=/path/to/smart-turn-v3.2-cpu.onnx
export LIVEKIT_TURN_MODEL_PATH=/path/to/model_q8.onnx
export LIVEKIT_TURN_MULTI_MODEL_PATH=/path/to/model_q8_multilingual.onnx
export LIVEKIT_TURN_TOKENIZER_PATH=/path/to/tokenizer.json
```

***

## CGO Dependencies

| Provider              | CGO dependency                  |
| --------------------- | ------------------------------- |
| Silence-Based         | None                            |
| Pipecat Smart Turn    | ONNX Runtime (`libonnxruntime`) |
| LiveKit Turn Detector | ONNX Runtime (`libonnxruntime`) |

***

## Providers

| Provider                                                                    | Approach                                     | Best for                                        |
| --------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------- |
| **[Silence-Based](/opensource/services/assistant-api/eos/silence-based)**   | Fixed silence timer                          | Simple, predictable — the default               |
| **[Pipecat Smart Turn](/opensource/services/assistant-api/eos/pipecat)**    | Audio model (prosodic cues)                  | Callers who pause mid-sentence                  |
| **[LiveKit Turn Detector](/opensource/services/assistant-api/eos/livekit)** | Language model (text + conversation history) | Structured data collection (addresses, numbers) |

See the [EOS concepts guide](/assistants/end-of-speech) for detailed parameter tuning guidance and use-case recommendations.


# Pipecat Smart Turn EOS
Source: https://doc.rapida.ai/opensource/services/assistant-api/eos/pipecat

Configure Pipecat Smart Turn end-of-speech detection in assistant-api.

[Pipecat Smart Turn](https://github.com/pipecat-ai/smart-turn) uses a Whisper-based audio model (\~8 MB) to predict turn completion directly from speech audio. It detects prosodic cues — falling intonation, speech rate changes — that indicate a caller has finished speaking.

**Provider identifier:** `pipecat_smart_turn_eos`

***

## Source Location

```
api/assistant-api/internal/end_of_speech/internal/pipecat/
├── pipecat_end_of_speech.go   # Main implementation
├── turn_detector.go           # ONNX inference wrapper
├── models/
│   └── smart-turn-v3.2-cpu.onnx   # Downloaded at Docker build (~8 MB)
```

***

## How It Works

1. `UserAudioPacket` audio is accumulated in a rolling float32 buffer (max \~5 seconds at 16 kHz)
2. When a final `SpeechToTextPacket` arrives, the model runs inference on the buffered audio
3. The model outputs a turn-completion probability (0.0 – 1.0)
4. If `probability >= threshold` → set timer to `quick_timeout` (caller is likely done)
5. If `probability < threshold` → set timer to `silence_timeout` (caller is likely still speaking)
6. Interim transcripts reset the timer to `fallback_timeout`
7. When the timer fires, `EndOfSpeechPacket` is emitted

```
Audio → buffer (rolling ~5s)
STT final → model inference → P(complete) = 0.73
  0.73 >= 0.5 (threshold) → timer = 200ms (quick)
  ...silence...
  Timer fires → EndOfSpeechPacket
```

***

## Parameters

| Option Key                       | Default   | Range       | Description                                                     |
| -------------------------------- | --------- | ----------- | --------------------------------------------------------------- |
| `microphone.eos.threshold`       | `0.5`     | 0.1–0.9     | Turn completion probability threshold                           |
| `microphone.eos.quick_timeout`   | `250 ms`  | 50–1000 ms  | Silence buffer when model says "done"                           |
| `microphone.eos.silence_timeout` | `2000 ms` | 500–5000 ms | Silence duration when model says "still speaking"               |
| `microphone.eos.timeout`         | `500 ms`  | 500–4000 ms | Fallback timeout for interim transcripts and inference failures |

***

## Model Setup

### Docker

The model is downloaded from Hugging Face during the Docker build and patched for ONNX Runtime compatibility. No manual action required.

```env theme={null}
# Set automatically in the Dockerfile
PIPECAT_TURN_MODEL_PATH=./models/pipecat_turn/smart-turn-v3.2-cpu.onnx
```

### From Source

Download the model manually:

```bash theme={null}
mkdir -p api/assistant-api/internal/end_of_speech/internal/pipecat/models

curl -fsSL -o api/assistant-api/internal/end_of_speech/internal/pipecat/models/smart-turn-v3.2-cpu.onnx \
    "https://huggingface.co/pipecat-ai/smart-turn-v3/resolve/main/smart-turn-v3.2-cpu.onnx"
```

If you encounter ONNX opset errors, patch the model:

```bash theme={null}
pip install onnx
python3 -c "
import onnx
m = onnx.load('api/assistant-api/internal/end_of_speech/internal/pipecat/models/smart-turn-v3.2-cpu.onnx')
m.ir_version = 9
used = {n.domain for n in m.graph.node}
keep = [o for o in m.opset_import if o.domain == '' or o.domain in used]
del m.opset_import[:]
m.opset_import.extend(keep)
onnx.save(m, 'api/assistant-api/internal/end_of_speech/internal/pipecat/models/smart-turn-v3.2-cpu.onnx')
"
```

To override the model path:

```bash theme={null}
export PIPECAT_TURN_MODEL_PATH=/path/to/smart-turn-v3.2-cpu.onnx
```

Requires ONNX Runtime (`libonnxruntime`) — same dependency as Silero/FireRed VAD.


# Silence-Based EOS
Source: https://doc.rapida.ai/opensource/services/assistant-api/eos/silence-based

Configure silence-based end-of-speech detection in assistant-api.

Silence-Based EOS triggers end-of-speech after a fixed duration of silence following the last speech activity or transcript. No ML model, no inference overhead.

**Provider identifier:** `silence_based_eos`

***

## Source Location

```
api/assistant-api/internal/end_of_speech/internal/silence_based/
└── silence_based_end_of_speech.go
```

***

## How It Works

1. A single worker goroutine manages a timer
2. When a final `SpeechToTextPacket` arrives, text is accumulated and the timer is set to `timeout`
3. When an interim `SpeechToTextPacket` arrives, the timer resets
4. When VAD is active, the timer stores a pending final instead of completing immediately
5. When VAD ends, pending EOS fires immediately; if VAD end is missing, the recovery timer fires it
6. State resets for the next turn

```
STT final → accumulate text → start timer (1000ms)
STT interim → reset timer
VAD start → block completion
VAD end → flush pending final
...silence...
Timer fires → EndOfSpeechPacket → LLM starts
```

***

## Parameters

| Option Key               | Default   | Range       | Description                                      |
| ------------------------ | --------- | ----------- | ------------------------------------------------ |
| `microphone.eos.timeout` | `1000 ms` | 500–4000 ms | Silence duration before triggering end-of-speech |

The UI sets a default of **700 ms** when switching to this provider. The backend default (when no value is configured) is **1000 ms**.

***

## Setup

No model files or downloads required. Works out of the box with both Docker and source builds.

To select this provider, set `microphone.eos.provider` to `silence_based_eos` in the assistant's audio options (or leave it unset — it is the default).


# Local Telephony with ngrok
Source: https://doc.rapida.ai/opensource/services/assistant-api/ngrok

Use ngrok to expose assistant-api to Twilio, Vonage, and Exotel webhooks during local development.

## Why ngrok is Required

Twilio, Vonage, and Exotel use a two-step call setup:

1. They send an HTTP POST webhook to your server when a call arrives
2. They open a WebSocket to your server to stream bidirectional audio

Both connections come **from the provider's cloud** to your machine. During local development your machine is not publicly reachable, so you need ngrok to create an HTTPS tunnel.

```
Twilio/Vonage/Exotel cloud
        │
        ▼
ngrok tunnel (https://xyz.ngrok.io)
        │
        ▼
localhost:8080  →  Nginx  →  assistant-api:9007
```

<Info>
  You need a single ngrok tunnel pointing to port `8080` (the Nginx gateway). All webhook and WebSocket traffic flows through Nginx and is proxied to `assistant-api`.
</Info>

***

## Prerequisites

| Tool         | Version | Install                                          |
| ------------ | ------- | ------------------------------------------------ |
| ngrok        | v3+     | [ngrok.com/download](https://ngrok.com/download) |
| Rapida stack | running | `make up-all`                                    |

***

## Step-by-Step Setup

<Steps>
  <Step title="Install and authenticate ngrok">
    ```bash theme={null}
    # macOS (Homebrew)
    brew install ngrok/ngrok/ngrok

    # Linux
    curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
    echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
    sudo apt update && sudo apt install ngrok
    ```

    Sign in and set your authtoken (required for stable subdomains):

    ```bash theme={null}
    ngrok config add-authtoken <your-authtoken>
    ```

    Get your authtoken at [dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).
  </Step>

  <Step title="Start the tunnel">
    ```bash theme={null}
    ngrok http 8080
    ```

    ngrok outputs a forwarding URL like:

    ```
    Forwarding  https://abc123.ngrok-free.app -> http://localhost:8080
    ```

    Copy the `https://` URL — this is your `PUBLIC_ASSISTANT_HOST`.

    <Note>
      The free tier generates a random URL on each restart. To get a stable URL across restarts, use a paid ngrok plan with a reserved domain.
    </Note>
  </Step>

  <Step title="Update PUBLIC_ASSISTANT_HOST in assistant-api">
    Edit `docker/assistant-api/.assistant.env`:

    ```env theme={null}
    # Replace with your ngrok hostname (without https://)
    PUBLIC_ASSISTANT_HOST=abc123.ngrok-free.app
    ```
  </Step>

  <Step title="Update media URL in the UI config">
    Edit `ui/src/configs/config.development.json`:

    ```json theme={null}
    {
        "connection": {
            "assistant": "http://localhost:8080",
            "web": "http://localhost:8080",
            "endpoint": "http://localhost:8080",
            "media": "https://abc123.ngrok-free.app",
            "socket": "localhost:4573",
            "sip": "localhost:5060"
        }
    }
    ```

    The `media` field is the public URL the browser and telephony providers use for WebSocket connections.
  </Step>

  <Step title="Restart assistant-api and the UI">
    ```bash theme={null}
    make rebuild-assistant   # Picks up the new PUBLIC_ASSISTANT_HOST
    ```

    If running the UI in development mode:

    ```bash theme={null}
    cd ui && yarn start:dev
    ```
  </Step>

  <Step title="Verify the tunnel is proxying correctly">
    ```bash theme={null}
    curl https://abc123.ngrok-free.app/readiness/
    # Expected: {"status":"ok"} or similar
    ```

    You can also check the ngrok web inspector at **[http://localhost:4040](http://localhost:4040)** to see incoming requests in real time.
  </Step>
</Steps>

***

## Configuring Twilio for Local Testing

With ngrok running, point your Twilio phone number's webhook to:

```
POST https://abc123.ngrok-free.app/v1/talk/twilio/call/{your-assistant-id}
```

<Tabs>
  <Tab title="Inbound call">
    1. Open [Twilio Console → Phone Numbers → Active Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
    2. Select your number
    3. Under **Voice Configuration**, set:

    | Field           | Value                                                             |
    | --------------- | ----------------------------------------------------------------- |
    | A call comes in | Webhook                                                           |
    | URL             | `https://abc123.ngrok-free.app/v1/talk/twilio/call/{assistantId}` |
    | HTTP Method     | POST                                                              |

    4. Call the number — Twilio posts the webhook to ngrok, which forwards to your local assistant-api
  </Tab>

  <Tab title="Outbound call">
    Outbound calls are initiated from your code — no additional webhook configuration is needed. Twilio will connect its WebSocket media stream back to `wss://abc123.ngrok-free.app/v1/talk/twilio/ctx/{contextId}`, which is generated automatically from `PUBLIC_ASSISTANT_HOST`.

    ```bash theme={null}
    curl -X POST http://localhost:8080/v1/talk/call \
      -H "Authorization: Bearer <your-api-key>" \
      -H "Content-Type: application/json" \
      -d '{
        "assistant": { "assistant_id": 123456789 },
        "to_number": "+15551234567",
        "from_number": "+15559876543"
      }'
    ```
  </Tab>
</Tabs>

***

## Configuring Vonage for Local Testing

Point your Vonage Application's **Answer URL** to:

```
POST https://abc123.ngrok-free.app/v1/talk/vonage/call/{your-assistant-id}
```

1. Open [Vonage Dashboard → Applications](https://dashboard.nexmo.com/applications) → select your app
2. Under **Capabilities → Voice → Answer URL**, set the URL above
3. Set **Event URL** to: `https://abc123.ngrok-free.app/v1/talk/vonage/ctx/{contextId}/event`

***

## Configuring Exotel for Local Testing

In your Exotel App (applet), set the webhook URL to:

```
https://abc123.ngrok-free.app/v1/talk/exotel/call/{your-assistant-id}
```

***

## Two Configurations Always Need Updating

When your ngrok URL changes (e.g., after a free-tier restart), update **both** of these:

| File                                     | Field                   | Value                                             |
| ---------------------------------------- | ----------------------- | ------------------------------------------------- |
| `docker/assistant-api/.assistant.env`    | `PUBLIC_ASSISTANT_HOST` | `abc123.ngrok-free.app` (no `https://`)           |
| `ui/src/configs/config.development.json` | `connection.media`      | `https://abc123.ngrok-free.app` (with `https://`) |

Then restart:

```bash theme={null}
make rebuild-assistant
# restart UI if needed: cd ui && yarn start:dev
```

***

## Stable URLs (Recommended for Team Development)

Using a random URL is inconvenient for team development since the webhook URL in Twilio/Vonage must be updated every time ngrok restarts. Options for a stable URL:

| Option                    | Description                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **ngrok reserved domain** | Paid ngrok plan — assign a fixed subdomain                                                   |
| **ngrok static domain**   | Free tier offers one free static domain: `ngrok http --domain=your-name.ngrok-free.app 8080` |
| **Cloudflare Tunnel**     | Free alternative — `cloudflared tunnel --url http://localhost:8080`                          |

With a static/reserved domain, you set the webhook URL in Twilio/Vonage once and never update it.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook returns 502 Bad Gateway">
    The Rapida stack is not running. Verify:

    ```bash theme={null}
    make status      # All containers should show "Up"
    make logs-all    # Check for startup errors
    ```
  </Accordion>

  <Accordion title="Audio connects but there is no voice / silence">
    `PUBLIC_ASSISTANT_HOST` is still set to the old ngrok URL or to `localhost`. Update it to the new ngrok hostname and run `make rebuild-assistant`.
  </Accordion>

  <Accordion title="ngrok shows 'ERR_NGROK_3200: tunnel not found'">
    The tunnel is not running. Start it again:

    ```bash theme={null}
    ngrok http 8080
    ```

    And update both `PUBLIC_ASSISTANT_HOST` and `connection.media` with the new URL.
  </Accordion>

  <Accordion title="Twilio error: 'Not a valid https URL'">
    Twilio requires HTTPS. ngrok provides HTTPS automatically. Do not use the `http://` version of the URL — always use the `https://abc123.ngrok-free.app` URL in Twilio's console.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Telephony Setup" icon="phone" href="/opensource/services/assistant-api/telephony">
    Full provider setup — Twilio, Vonage, Exotel, Asterisk, SIP.
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    All PUBLIC\_ASSISTANT\_HOST and SIP variables.
  </Card>
</CardGroup>


# Assistant API
Source: https://doc.rapida.ai/opensource/services/assistant-api/overview

Voice orchestration hub. Manages the full real-time pipeline — STT, LLM, TTS — across WebSocket, telephony, and SIP channels.

## Purpose

The `assistant-api` is the runtime core of the Rapida platform. Every active voice call passes through this service. It owns:

* Real-time audio streaming via WebSocket (browser and telephony)
* Voice Activity Detection (Silero, TEN, FireRed) — speech detection and barge-in
* Speech-to-text transcription (streaming, provider-agnostic)
* End of Speech detection (Silence-Based, Pipecat Smart Turn, LiveKit Turn Detector) — turn boundary detection
* LLM inference via `integration-api` (streaming token delivery)
* Text-to-speech synthesis (streaming, provider-agnostic)
* Telephony signalling for Twilio, Vonage, Exotel, Asterisk, and SIP
* Knowledge base retrieval (RAG) via `document-api`
* Conversation state and metrics persistence

<CardGroup>
  <Card title="Port" icon="server">
    `9007` — HTTP · gRPC · WebSocket (cmux)
  </Card>

  <Card title="Port" icon="phone">
    `4573` — Asterisk AudioSocket (TCP)
  </Card>

  <Card title="Language" icon="code">
    Go 1.25
    Gin (REST) + gRPC
  </Card>
</CardGroup>

***

## Voice Pipeline

Every call follows this sequence. STT, LLM, and TTS run as streaming pipelines — the LLM begins generating before STT finishes, and TTS begins speaking before the LLM completes.

```mermaid theme={null}
sequenceDiagram
    participant Client as Client (Browser / Phone)
    participant AS as assistant-api :9007
    participant IA as integration-api :9004
    participant DA as document-api :9010

    Client->>AS: Audio stream (PCM 16kHz / μ-law)
    AS->>AS: VAD → speech detection + barge-in
    AS->>AS: STT transformer → text transcript
    AS->>AS: EOS → turn boundary detection
    AS->>DA: Semantic search (if knowledge base attached)
    DA-->>AS: Top-k relevant chunks
    AS->>IA: StreamChatCompletion(messages + context)
    IA-->>AS: Token stream (delta messages)
    AS->>AS: TTS transformer → audio chunks
    AS-->>Client: Audio stream (PCM / μ-law)
```

***

## Input Channels

| Channel              | Transport                                            | Entry Point                                                    | Use Case                |
| -------------------- | ---------------------------------------------------- | -------------------------------------------------------------- | ----------------------- |
| WebSocket (browser)  | `wss://host:8080/talk_api.TalkService/AssistantTalk` | gRPC-web                                                       | Web widget, SDK         |
| Twilio               | WebSocket per call                                   | `wss://PUBLIC_ASSISTANT_HOST/v1/talk/twilio/ctx/{contextId}`   | Inbound / outbound PSTN |
| Vonage               | WebSocket per call                                   | `wss://PUBLIC_ASSISTANT_HOST/v1/talk/vonage/ctx/{contextId}`   | Inbound / outbound PSTN |
| Exotel               | WebSocket per call                                   | `wss://PUBLIC_ASSISTANT_HOST/v1/talk/exotel/ctx/{contextId}`   | India / SEA PSTN        |
| Asterisk AudioSocket | TCP `0.0.0.0:4573`                                   | Raw TCP (AudioSocket protocol)                                 | Self-hosted PBX         |
| Asterisk WebSocket   | WebSocket per call                                   | `wss://PUBLIC_ASSISTANT_HOST/v1/talk/asterisk/ctx/{contextId}` | Self-hosted PBX         |
| SIP                  | UDP `0.0.0.0:5090`                                   | SIP INVITE                                                     | Direct SIP / Asterisk   |

<Info>
  `PUBLIC_ASSISTANT_HOST` must be a publicly reachable hostname or IP. Twilio, Vonage, and Exotel call back to this host for WebSocket media streaming.
</Info>

***

## STT / TTS Providers

| Provider Identifier     | STT | TTS | Notes                                |
| ----------------------- | --- | --- | ------------------------------------ |
| `deepgram`              | ✅   | ✅   | Nova-2 / Nova-3; streaming           |
| `google-speech-service` | ✅   | ✅   | Streaming STT; WaveNet / Neural2 TTS |
| `azure-speech-service`  | ✅   | ✅   | Neural voices; streaming             |
| `elevenlabs`            | ✗   | ✅   | High-fidelity voice cloning          |
| `cartesia`              | ✅   | ✅   | Low-latency streaming                |
| `assemblyai`            | ✅   | ✗   | Streaming + batch                    |
| `sarvamai`              | ✅   | ✅   | Indian languages                     |
| `revai`                 | ✅   | ✗   | Streaming STT                        |

Provider identifiers are the string constants used in `AudioTransformer` (`api/assistant-api/internal/transformer/transformer.go`). They map directly to the `provider` field in the assistant configuration.

***

## Key Components

<AccordionGroup>
  <Accordion title="Transformer Layer (STT / TTS)">
    Each provider lives under `api/assistant-api/internal/transformer/<provider>/`. All providers implement the same generic interface:

    ```go theme={null}
    // api/assistant-api/internal/type/transformer.go
    type Transformers[IN any] interface {
        Initialize() error
        Transform(context.Context, IN) error
        Close(context.Context) error
    }
    ```

    The factory functions resolve the provider string to a concrete implementation at call time:

    ```go theme={null}
    // api/assistant-api/internal/transformer/transformer.go
    func GetSpeechToTextTransformer(ctx, logger, provider, credential, onPacket, opts) (SpeechToTextTransformer, error)
    func GetTextToSpeechTransformer(ctx, logger, provider, credential, onPacket, opts) (TextToSpeechTransformer, error)
    ```

    See [STT / TTS Providers](/opensource/services/assistant-api/stt-tts) for how to add a new provider.
  </Accordion>

  <Accordion title="Telephony Channel Layer">
    Telephony providers live under `api/assistant-api/internal/channel/telephony/internal/<provider>/`. The factory in `telephony.go` creates the correct provider at runtime:

    ```go theme={null}
    // api/assistant-api/internal/channel/telephony/telephony.go
    const (
        Twilio   Telephony = "twilio"
        Exotel   Telephony = "exotel"
        Vonage   Telephony = "vonage"
        Asterisk Telephony = "asterisk"
        SIP      Telephony = "sip"
    )
    ```

    All providers implement the `Telephony` interface (`ReceiveCall`, `OutboundCall`, `InboundCall`, `StatusCallback`). See [Telephony](/opensource/services/assistant-api/telephony) for provider setup.
  </Accordion>

  <Accordion title="Call Context Store">
    Call context (assistant ID, conversation ID, auth token, provider, caller number) is persisted in PostgreSQL via the `callcontext.Store` interface. The context ID is passed through the call URL path so the WebSocket or AudioSocket handler can resolve the full session without requiring the client to re-authenticate.
  </Accordion>

  <Accordion title="Communication Interface">
    The `Communication` interface in `api/assistant-api/internal/type/` is the central contract tying together the STT callback, LLM execution, TTS callback, auth, tracing, and conversation state for a single call. Each channel (WebSocket, telephony, SIP) creates a `Communication` implementation per call.
  </Accordion>
</AccordionGroup>

***

## Running

<Tabs>
  <Tab title="Docker Compose">
    ```bash theme={null}
    # Start assistant-api and its dependencies
    make up-assistant

    # Follow logs
    make logs-assistant

    # Rebuild after code changes
    make rebuild-assistant

    # Shell access
    make shell-assistant
    ```
  </Tab>

  <Tab title="From Source">
    Requires Go 1.25, PostgreSQL 15, Redis 7, and OpenSearch 2.11 running locally.

    ```bash theme={null}
    # Load env file
    export $(grep -v '^#' docker/assistant-api/.assistant.env | xargs)

    # Override Docker hostnames
    export POSTGRES__HOST=localhost
    export REDIS__HOST=localhost
    export OPENSEARCH__HOST=localhost
    export INTEGRATION_HOST=localhost:9004
    export ENDPOINT_HOST=localhost:9005
    export WEB_HOST=localhost:9001
    export DOCUMENT_HOST=http://localhost:9010

    # Run
    go run cmd/assistant/assistant.go
    ```
  </Tab>
</Tabs>

***

## Health Endpoints

| Endpoint          | Purpose                                           |
| ----------------- | ------------------------------------------------- |
| `GET /readiness/` | Service ready (DB + Redis + OpenSearch connected) |
| `GET /healthz/`   | Liveness probe                                    |

```bash theme={null}
curl http://localhost:9007/readiness/
```

***

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    All environment variables with defaults and descriptions.
  </Card>

  <Card title="Voice Activity Detection" icon="audio-waveform" href="/opensource/services/assistant-api/vad/overview">
    Silero, TEN, and FireRed VAD — setup, parameters, and model files.
  </Card>

  <Card title="End of Speech" icon="timer" href="/opensource/services/assistant-api/eos/overview">
    Silence-Based, Pipecat Smart Turn, and LiveKit Turn Detector — setup and model downloads.
  </Card>

  <Card title="STT / TTS Providers" icon="mic" href="/opensource/services/assistant-api/stt-tts">
    Supported providers, the transformer interface, and how to add a new provider.
  </Card>

  <Card title="Telephony" icon="phone" href="/opensource/services/assistant-api/telephony">
    Twilio, Vonage, Exotel, Asterisk AudioSocket, and SIP setup.
  </Card>

  <Card title="Integration API" icon="plug" href="/opensource/services/integration-api/overview">
    LLM provider execution layer called by assistant-api.
  </Card>
</CardGroup>


# Assistant API — Prompt Templating
Source: https://doc.rapida.ai/opensource/services/assistant-api/prompt-templating

Prompt argument pipeline, variable namespaces, and rendering behavior in model executor.

## Scope

| Area                     | Implemented in                                           |
| ------------------------ | -------------------------------------------------------- |
| Request pipeline         | `pipeline_request.go`                                    |
| Response pipeline        | `pipeline_response.go`                                   |
| Pipeline types           | `pipeline_types.go`                                      |
| Template rendering       | `pkg/clients/integration/builders/chat_input_builder.go` |
| Template parser          | `pkg/parsers/pongo2.template.parser.go`                  |
| Argument merge semantics | `pkg/utils/collection.go`                                |
| Behavior tests           | `model_test.go`                                          |

***

## Request Pipeline Stages

For each `UserTextPacket`, stages run in this order:

| Order | Stage name                 | Output                         |
| ----- | -------------------------- | ------------------------------ |
| 1     | `build_user_message`       | `pipeline.UserMessage`         |
| 2     | `snapshot_history`         | history snapshot               |
| 3     | `validate_history`         | validates tool-call sequencing |
| 4     | `prepare_prompt_arguments` | `pipeline.PromptArgs`          |

Stage order is validated by `TestRequestPipeline_DefaultStages`.

***

## Prompt Argument Map

`buildPromptContext()` creates these top-level keys:

| Key            | Contents                                          |
| -------------- | ------------------------------------------------- |
| `system`       | current UTC date/time values                      |
| `assistant`    | assistant metadata                                |
| `conversation` | conversation metadata                             |
| `session`      | session mode (if available)                       |
| `message`      | current or reconstructed user message context     |
| `args`         | namespaced conversation args                      |
| root args      | flattened copy of conversation args at root level |

Deep clone is applied before use (`clonePromptArguments`).

***

## General Jinja-Style Guidelines

Template rendering is performed by Pongo2 (`pkg/parsers/pongo2.template.parser.go`), which follows Jinja-style syntax.

Verified patterns from parser tests:

| Pattern                | Example                                        | Reference                               |
| ---------------------- | ---------------------------------------------- | --------------------------------------- |
| Variable interpolation | `{{ name }}`                                   | `TestPongo2StringTemplateParser_Parse`  |
| Conditional block      | `{% if age > 20 %}...{% endif %}`              | `TestPongo2MessageTemplateParser_Parse` |
| Loop block             | `{% for message in messages %}...{% endfor %}` | `TestPongo2TemplateParser_Parse`        |
| Autoescape control     | `{% autoescape off %}...{% endautoescape %}`   | `TestPongo2TemplateParser_Parse`        |

Execution behavior:

| Case                | Behavior                                         |
| ------------------- | ------------------------------------------------ |
| Parse/execute error | parser returns original template string          |
| Successful parse    | rendered template string is used in chat request |

***

## Argument Namespaces

### `system.*`

| Field              | Format       |
| ------------------ | ------------ |
| `current_date`     | `YYYY-MM-DD` |
| `current_time`     | `HH:MM:SS`   |
| `current_datetime` | RFC3339      |
| `day_of_week`      | weekday name |
| `date_rfc1123`     | RFC1123      |
| `date_unix`        | seconds      |
| `date_unix_ms`     | milliseconds |

All are UTC.

### `assistant.*`

| Field                   |
| ----------------------- |
| `assistant.name`        |
| `assistant.id` (string) |
| `assistant.language`    |
| `assistant.description` |

### `conversation.*`

| Field                                      |
| ------------------------------------------ |
| `conversation.id`                          |
| `conversation.identifier`                  |
| `conversation.source`                      |
| `conversation.direction`                   |
| `conversation.created_date` (if available) |
| `conversation.updated_date` (if available) |
| `conversation.duration` (best effort)      |

### `session.*`

| Field          | Condition                                   |
| -------------- | ------------------------------------------- |
| `session.mode` | only when communication exposes `GetMode()` |

### `message.*`

| Field              |
| ------------------ |
| `message.text`     |
| `message.language` |

***

## Args Behavior (Namespaced + Root)

Conversation args are merged twice:

| Access form | Example           |
| ----------- | ----------------- |
| namespaced  | `{{ args.name }}` |
| root-level  | `{{ name }}`      |

Implementation merge:

```go theme={null}
utils.MergeMaps(
  map[string]interface{}{"args": args},
  args,
)
```

Behavior is validated by `TestBuildPromptContext_ArgumentsRemainRootLevel`.

***

## Template Rendering Contract

`buildChatRequest()` renders prompt templates and prepends rendered system/template messages before runtime history.

### Argument merge precedence for rendering

```go theme={null}
utils.MergeMaps(
  e.inputBuilder.PromptArguments(template.Variables),
  promptArguments,
)
```

| Source                                         | Priority |
| ---------------------------------------------- | -------- |
| template variable defaults (`promptVariables`) | lower    |
| runtime prompt args                            | higher   |

Parser behavior (`pongo2`):

| Case                     | Result                           |
| ------------------------ | -------------------------------- |
| parse or execute error   | returns original template string |
| successful parse/execute | returns rendered text            |

***

## Response + Tool Follow-up Argumentation

On response handling, prompt args are rebuilt via `preparePromptArgumentsForResponse()` before tool follow-up send.

Language precedence for response flow:

| Priority | Source                                                 |
| -------- | ------------------------------------------------------ |
| 1        | latest user language in `communication.GetHistories()` |
| 2        | `communication.GetMetadata()["client.language"]`       |
| 3        | empty string                                           |

Validated by:

* `TestPreparePromptArgumentsForResponse_UsesLatestUserAndClientLanguage`
* `TestPreparePromptArgumentsForResponse_PrefersLatestHistoryLanguage`
* `TestHandleResponse_ToolFollowUpRetainsUserMessageContext`

***

## History Validation Rules

Before sending chat requests, history must satisfy these rules:

| Rule                                                              | Enforced by               |
| ----------------------------------------------------------------- | ------------------------- |
| assistant tool call must be immediately followed by tool response | `validateHistorySequence` |
| tool response IDs must match tool call IDs                        | `validateToolIDMatch`     |
| orphan tool response not allowed                                  | `validateHistorySequence` |
| after tool response, next message (if any) must be assistant      | `validateHistorySequence` |

Validation coverage:

* `TestValidateHistorySequence_*`

***

## Internal Reference

* `api/assistant-api/internal/agent/executor/llm/internal/model/PROMPT_ARGUMENTS.md`


# AssemblyAI STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/assemblyai

Configure AssemblyAI real-time speech-to-text with speaker diarization in assistant-api.

AssemblyAI provides real-time streaming transcription with optional speaker diarization — useful for call center and multi-speaker scenarios.

**Provider identifier:** `assemblyai`

***

## Vault Credential

| Key   | Description                                                              |
| ----- | ------------------------------------------------------------------------ |
| `key` | AssemblyAI API key from [app.assemblyai.com](https://app.assemblyai.com) |

***

## Setup

<Steps>
  <Step title="Get an AssemblyAI API key">
    Sign in at [app.assemblyai.com](https://app.assemblyai.com) → **API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **AssemblyAI**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **AssemblyAI**.

    | Option           | Example | Description                |
    | ---------------- | ------- | -------------------------- |
    | `language`       | `en`    | Language code              |
    | `speaker_labels` | `true`  | Enable speaker diarization |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Deepgram" icon="audio-waveform" href="/opensource/services/assistant-api/stt/deepgram">
    Alternative STT provider with Nova-3
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# AWS Transcribe STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/aws

Configure AWS Transcribe speech-to-text via HTTP in assistant-api.

AWS Transcribe provides automatic speech recognition via Amazon Web Services. It supports a broad set of languages and dialects with streaming transcription for real-time voice assistant pipelines.

**Provider identifier:** `aws`

***

## Vault Credentials

| Key                 | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `access_key_id`     | AWS Access Key ID from your IAM user or role                     |
| `secret_access_key` | AWS Secret Access Key corresponding to the Access Key ID         |
| `region`            | AWS region where Transcribe requests are sent (e.g. `us-east-1`) |

***

## Setup

<Steps>
  <Step title="Create AWS credentials with Transcribe access">
    In the [AWS IAM console](https://console.aws.amazon.com/iam/) → **Users → Create User** → attach the `AmazonTranscribeFullAccess` policy (or a scoped custom policy). Generate an access key pair under **Security credentials**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **AWS**, enter `access_key_id`, `secret_access_key`, and `region`.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **AWS Transcribe**.

    | Option     | Example | Description                                                                                                       |
    | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
    | `language` | `en-US` | Language code: `en-US`, `en-GB`, `es-US`, `fr-FR`, `de-DE`, `it-IT`, `pt-BR`, `ja-JP`, `ko-KR`, `zh-CN`, and more |

    See the full list of supported languages in the [AWS Transcribe documentation](https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="AWS Polly TTS" icon="microphone" href="/opensource/services/assistant-api/tts/aws">
    AWS text-to-speech with Polly
  </Card>

  <Card title="STT Overview" icon="waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Azure STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/azure

Configure Azure Cognitive Services Speech-to-Text in assistant-api.

Azure Cognitive Services Speech provides real-time streaming transcription with Neural Speech models and support for 140+ languages.

**Provider identifier:** `azure-speech-service`

***

## Vault Credential

| Key      | Description                               |
| -------- | ----------------------------------------- |
| `key`    | Azure Speech subscription key             |
| `region` | Azure region, e.g. `eastus`, `westeurope` |

***

## Setup

<Steps>
  <Step title="Create an Azure Speech resource">
    In [Azure Portal](https://portal.azure.com) → **Create a resource → AI + Machine Learning → Speech**. Copy the **Key 1** and **Region**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Azure Speech**, enter `key` = subscription key and `region` = Azure region.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Azure Speech**.

    | Option     | Example  | Description          |
    | ---------- | -------- | -------------------- |
    | `language` | `en-US`  | BCP-47 language code |
    | `model`    | `latest` | Speech model version |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Azure TTS" icon="volume" href="/opensource/services/assistant-api/tts/azure">
    Azure Neural text-to-speech
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Custom STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/custom

Configure a custom WebSocket or HTTP speech-to-text provider in Rapida.

Custom STT lets you connect Rapida to a WebSocket or HTTP transcription service without writing a new Go transformer. The UI stores provider credentials and assistant options; `assistant-api` reads them through the `custom-stt` transformer and maps audio packets and provider responses with DSL rules.

**Provider identifier:** `custom-stt`

***

## Where it is configured

<Steps>
  <Step title="Create the provider credential">
    In the Rapida dashboard, open **Integrations > Models**, choose **Custom STT**, and create a credential.

    | Credential field   | Required | Value                                                                                                                                             |
    | ------------------ | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `apiCompatibility` |       No | `websocket_v1` or `http_v1`. Defaults to `websocket_v1` when omitted.                                                                             |
    | `baseUrl`          |      Yes | WebSocket URL or HTTP endpoint URL for your STT service, for example `wss://stt.example.com/v1/listen` or `https://stt.example.com/v1/transcribe` |
    | `headers`          |       No | Header map sent on the WebSocket handshake or HTTP request, for example `{"Authorization":"Bearer sk_..."}`                                       |

    The backend also accepts snake case keys: `api_compatibility` and `base_url`.
  </Step>

  <Step title="Select Custom STT on the assistant">
    Open the assistant voice settings and select **Custom STT** as the speech-to-text provider.
  </Step>

  <Step title="Fill the STT arguments">
    Set the audio format, query parameters, request rules, and response rules. The argument reference below maps to the UI fields and the transformer option keys.
  </Step>
</Steps>

***

## STT arguments

The custom STT transformer reads the option keys shown below. The current UI exposes the audio and DSL fields; `listen.model` and `listen.language` are optional API/import metadata keys that request rules and query parameters can read when present. The UI may preserve other microphone-level settings under `microphone.*`, but the custom STT DSL fields are unprefixed `listen.*` keys.

| Option key                 | Required | Default           | Description                                                                                                                                                                                             |
| -------------------------- | -------: | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listen.model`             |       No | Empty             | Optional provider model identifier. Reference it in DSL as `model` or `config.model`.                                                                                                                   |
| `listen.language`          |       No | Empty             | Optional provider language code. Reference it in DSL as `language` or `config.language`.                                                                                                                |
| `listen.audio.encoding`    |      Yes | `LINEAR16`        | Audio encoding setting exposed to the DSL as `encoding` and `config.audio.encoding`. For `websocket_v1`, binary audio is prepared with this encoding. Supported values: `LINEAR16`, `MuLaw8`.           |
| `listen.audio.sample_rate` |      Yes | `16000`           | Audio sample rate used while preparing audio and exposed to the DSL as `sample_rate` and `config.audio.sample_rate`. Supported UI values: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000`. |
| `listen.query_params`      |       No | `{}`              | Flat JSON object appended to `baseUrl` as query parameters. Values can use DSL expressions.                                                                                                             |
| `listen.request_rules`     |      Yes | See example below | Ordered JSON array that tells Rapida what to send for each outbound packet. Must contain at least one `audio` rule.                                                                                     |
| `listen.response_rules`    |      Yes | None              | Ordered JSON array that tells Rapida how to parse provider WebSocket frames or HTTP response bodies into transcripts or errors.                                                                         |

***

## Query parameters

Use `listen.query_params` when your provider expects configuration in the URL.

Supported variables:

| Variable      | Source                     |
| ------------- | -------------------------- |
| `model`       | `listen.model`             |
| `language`    | `listen.language`          |
| `encoding`    | `listen.audio.encoding`    |
| `sample_rate` | `listen.audio.sample_rate` |

```json theme={null}
{
  "language": { "$var": "language" },
  "model": { "$var": "model" },
  "encoding": { "$var": "encoding" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

***

## Request rules

Request rules are evaluated for normalized packets produced by Rapida.

| Packet        | When it is sent               | Available paths                                                                                                                                   |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `turn_change` | A new turn/context starts     | `packet.kind`, `packet.context_id`, `config.model`, `config.language`, `config.audio.encoding`, `config.audio.sample_rate`                        |
| `audio`       | Audio is ready to send        | `packet.kind`, `packet.context_id`, `packet.audio.bytes`, `packet.audio.base64`, `packet.audio.pcm_base64`, `packet.audio.wav_base64`, `config.*` |
| `interrupt`   | User interruption is detected | `packet.kind`, `packet.context_id`, `config.*`                                                                                                    |

Supported outbound frame types are `binary`, `json`, and `text`.

<Note>
  `packet.audio.bytes` is raw audio bytes for binary frames. Use `packet.audio.base64` when the provider expects audio inside a JSON payload.
</Note>

### Binary audio stream

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  }
]
```

### JSON audio payload

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "json",
      "body": {
        "audio": { "$path": "packet.audio.base64" },
        "encoding": { "$path": "config.audio.encoding" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  }
]
```

### HTTP transcription request

Use this shape with `apiCompatibility = http_v1` when your provider accepts a JSON POST after each completed speech segment.

```json theme={null}
[
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "json",
      "body": {
        "audio": { "$path": "packet.audio.wav_base64" },
        "encoding": { "$path": "config.audio.encoding" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  }
]
```

<Note>
  For `http_v1`, the first matching `audio` rule must use `send.frame = json`. WebSocket STT can use `binary`, `json`, or `text` outbound frames.
</Note>

***

## Response rules

Response rules parse provider WebSocket frames or HTTP response bodies into Rapida transcript packets.

Supported inbound frame types:

| Frame  | Use when                                    |
| ------ | ------------------------------------------- |
| `json` | The provider returns JSON messages.         |
| `text` | The provider returns plain transcript text. |

Supported emit keys:

| Emit key     | Type      | Description                                                              |
| ------------ | --------- | ------------------------------------------------------------------------ |
| `script`     | `string`  | Transcript text. When present, Rapida emits an STT transcript packet.    |
| `confidence` | `number`  | Optional transcript confidence.                                          |
| `language`   | `string`  | Optional language code for the transcript.                               |
| `interim`    | `boolean` | `true` for partial transcripts, `false` for final transcripts.           |
| `error`      | Any       | Provider error value. When present, Rapida treats the frame as an error. |

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "partial" },
    "emit": {
      "script": { "$path": "text" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "language": { "$path": "language" },
      "interim": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "final" },
    "emit": {
      "script": { "$path": "text" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "confidence" }
      },
      "language": { "$path": "language" },
      "interim": false
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "error": { "$path": "error.message" }
    }
  }
]
```

***

## STT DSL design

Custom STT uses a JSON-template DSL with three sections: query parameters, request rules, and response rules. The DSL is intentionally small. It does not run scripts, call functions, concatenate strings, perform regex matching, or read environment variables.

### STT frame support

| Frame type | Outbound request | Inbound response | Notes                                                        |
| ---------- | ---------------: | ---------------: | ------------------------------------------------------------ |
| `binary`   |              Yes |               No | Use for raw provider audio input.                            |
| `json`     |              Yes |              Yes | Use for provider control packets and structured transcripts. |
| `text`     |              Yes |              Yes | Use for providers that accept or return plain text frames.   |

Inbound parsing rules:

* WebSocket message type `2` is treated as `binary`, but STT response rules do not support binary response frames.
* Non-binary messages are parsed as JSON when they contain exactly one valid JSON value.
* Non-JSON messages are treated as `text`.
* For STT, JSON string primitives and non-object JSON values are treated as `text`; JSON response rules operate on JSON objects.

### STT operators

Every operator object must contain only that operator and its required field.

| Operator | Where supported                                 | Description                                                   |
| -------- | ----------------------------------------------- | ------------------------------------------------------------- |
| `$var`   | Query parameters                                | Reads `model`, `language`, `encoding`, or `sample_rate`.      |
| `$path`  | Request rules, response rules                   | Reads a dot path from request scope or a JSON response frame. |
| `$cast`  | Query parameters, request rules, response rules | Casts to `string`, `number`, or `boolean`.                    |
| `$frame` | Response rules                                  | Reads the full current `text` response frame.                 |

Unsupported STT operators:

* `$decode` is not supported for STT.
* `$frame: "binary"` and `$frame: "json"` are not supported for STT emit rules.

### Cast behavior

| Cast      | Behavior                                                                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`  | Converts strings, bytes, numbers, booleans, and null to string form.                                                                                              |
| `number`  | Converts JSON numbers, numeric values, or numeric strings to an integer or float.                                                                                 |
| `boolean` | Converts booleans, boolean strings, and numeric values. JSON numbers are accepted as `0` or `1`; typed numeric values use zero as `false` and non-zero as `true`. |

### JSON path behavior

`$path` uses dot-separated paths.

```json theme={null}
{ "$path": "packet.audio.base64" }
```

Objects are traversed by key. Arrays are traversed by numeric index.

```json theme={null}
{ "$path": "results.0.transcript" }
```

Limits:

* Keys containing a literal dot are not addressable.
* Request rules can only read from `config` and `packet`.
* Response rules can use `$path` only with JSON response frames.
* A missing path in `when.path` means the rule does not match.
* A missing path in `emit` or `send.body` is an error.

### Query parameter rules

`listen.query_params` must be a flat JSON object. In the UI, each value must resolve to a string, number, or boolean. The backend also accepts null values and skips them when building the URL. Nested objects and arrays are rejected unless the object is a DSL expression.

```json theme={null}
{
  "language": { "$var": "language" },
  "model": { "$var": "model" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

The rendered query parameters are appended to `baseUrl`. Existing query parameters in `baseUrl` are preserved unless the same key is rendered by `listen.query_params`.

### Request rule shape

`listen.request_rules` is an ordered JSON array. For `websocket_v1`, every matching rule is sent, so one packet can produce multiple WebSocket messages. For `http_v1`, the first matching `audio` rule provides the JSON POST body.

| Field         | Required | Description                             |
| ------------- | -------: | --------------------------------------- |
| `when.packet` |      Yes | `turn_change`, `audio`, or `interrupt`. |
| `send.frame`  |      Yes | `binary`, `json`, or `text`.            |
| `send.body`   |      Yes | Static value or DSL expression tree.    |

Body validation depends on `send.frame`:

| `send.frame` | `send.body` must resolve to                              |
| ------------ | -------------------------------------------------------- |
| `binary`     | Bytes or string.                                         |
| `json`       | Valid JSON value. Byte arrays are not valid JSON bodies. |
| `text`       | Value convertible to string.                             |

### STT request scope

The request scope is the data available to `$path` in request rules.

```json theme={null}
{
  "config": {
    "model": "model-a",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "audio",
    "context_id": "ctx_123",
    "audio": {
      "bytes": "<raw bytes>",
      "base64": "AAE=",
      "pcm_base64": "AAE=",
      "wav_base64": "UklGRi..."
    }
  }
}
```

`packet.audio` exists only for `audio` packets.

### Response rule shape

`listen.response_rules` is an ordered JSON array. The first matching rule is evaluated; later rules are skipped for that response.

| Field         | Required | Description                                                                   |
| ------------- | -------: | ----------------------------------------------------------------------------- |
| `when.frame`  |      Yes | `json` or `text`.                                                             |
| `when.path`   |       No | Dot path inside a JSON frame. Must be paired with `when.equals`.              |
| `when.equals` |       No | Primitive value compared against `when.path`, or against the full text frame. |
| `emit`        |      Yes | Object containing supported STT emit keys.                                    |

Match behavior:

| Frame  | Match behavior                                                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `json` | If `when.path` and `when.equals` are omitted, matches any JSON object. If provided, both fields are required and compared exactly.  |
| `text` | If `when.equals` is omitted, matches any text frame. If provided, compares the full text frame exactly. `when.path` is not allowed. |

### STT emit keys

| Emit key     | Type after evaluation | Effect                                                                    |
| ------------ | --------------------- | ------------------------------------------------------------------------- |
| `script`     | string                | Transcript text. Empty transcripts are ignored.                           |
| `confidence` | number                | Transcript confidence. Defaults to `0` when omitted.                      |
| `language`   | string                | Transcript language. Falls back to `listen.language` when omitted.        |
| `interim`    | boolean               | `true` emits an interim transcript; `false` emits a completed transcript. |
| `error`      | string                | Emits an STT error instead of a transcript.                               |

### Plain text transcript response

Use this for providers that return transcript chunks as raw text frames.

```json theme={null}
[
  {
    "when": { "frame": "text" },
    "emit": {
      "script": { "$frame": "text" },
      "interim": false
    }
  }
]
```

### Nested JSON transcript response

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "result.final", "equals": false },
    "emit": {
      "script": { "$path": "result.transcript" },
      "interim": true
    }
  },
  {
    "when": { "frame": "json", "path": "result.final", "equals": true },
    "emit": {
      "script": { "$path": "result.transcript" },
      "confidence": {
        "$cast": "number",
        "value": { "$path": "result.confidence" }
      },
      "language": { "$path": "result.language" },
      "interim": false
    }
  }
]
```

### Start, audio, and interrupt recipe

Use this pattern when the provider expects a session-start message, binary audio frames, and a flush message on interruption.

```json theme={null}
[
  {
    "when": { "packet": "turn_change" },
    "send": {
      "frame": "json",
      "body": {
        "type": "start",
        "language": { "$path": "config.language" },
        "sample_rate": {
          "$cast": "number",
          "value": { "$path": "config.audio.sample_rate" }
        }
      }
    }
  },
  {
    "when": { "packet": "audio" },
    "send": {
      "frame": "binary",
      "body": { "$path": "packet.audio.bytes" }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": { "type": "flush" }
    }
  }
]
```

### Runtime behavior

* The URL is built from `baseUrl` and `listen.query_params`.
* Headers are copied from the credential and are not templated.
* Audio is prepared before request rules are evaluated. WebSocket binary audio uses the configured encoding and sample rate; HTTP v1 request scope exposes PCM bytes plus PCM/WAV base64 for the completed speech segment.
* For `websocket_v1`, `turn_change` and `audio` packets open the WebSocket connection if needed.
* For `http_v1`, Rapida buffers audio while the user is speaking and sends one HTTP POST when the STT end packet arrives.
* `interrupt` rules are sent only by the WebSocket transport when a connection is already active.
* If no response rule matches an inbound frame, the frame is ignored.
* If a response emits `error`, Rapida emits an STT error packet.
* If a response emits non-empty `script`, Rapida emits a transcript packet and conversation event.

### Current STT limits

* No regex, contains, starts-with, greater-than, or compound match conditions.
* No string interpolation or concatenation.
* No fallback values inside expressions.
* No dynamic headers or dynamic URL path segments.
* No `$decode`.
* No binary response handling for STT.
* No `$frame: "json"` selector in emit rules.

***

## Backend mapping

`assistant-api` resolves `custom-stt` in `api/assistant-api/internal/transformer/transformer.go`, then dispatches by credential compatibility:

| `apiCompatibility`        | Implementation                                                   |
| ------------------------- | ---------------------------------------------------------------- |
| `websocket_v1` or omitted | `api/assistant-api/internal/transformer/custom/stt_websocket_v1` |
| `http_v1`                 | `api/assistant-api/internal/transformer/custom/stt_http_v1`      |

Both STT implementations validate:

* `baseUrl` is present in the credential.
* `listen.audio.encoding` is not empty.
* `listen.audio.sample_rate` is positive.
* `listen.request_rules` contains at least one `audio` packet rule.
* `listen.response_rules` contains at least one rule.

`http_v1` also requires the first matching `audio` request rule to emit a `json` frame because the transport sends an HTTP POST body.

<CardGroup>
  <Card title="Custom TTS" icon="volume" href="/opensource/services/assistant-api/tts/custom">
    Configure WebSocket text-to-speech.
  </Card>

  <Card title="STT overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    Transformer interface and supported providers.
  </Card>
</CardGroup>


# Deepgram STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/deepgram

Configure Deepgram Nova-2/Nova-3 speech-to-text in assistant-api.

Deepgram uses a persistent WebSocket connection via the Deepgram Go SDK. Audio is streamed continuously and transcripts are returned in real time.

**Provider identifier:** `deepgram`

***

## Vault Credential

| Key   | Description                                                                |
| ----- | -------------------------------------------------------------------------- |
| `key` | Deepgram API key from [console.deepgram.com](https://console.deepgram.com) |

***

## Setup

<Steps>
  <Step title="Get a Deepgram API key">
    Sign in at [console.deepgram.com](https://console.deepgram.com) → **API Keys → Create a new API key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Deepgram**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Deepgram**.

    Optional model parameters via assistant options:

    | Option      | Example  | Description                                   |
    | ----------- | -------- | --------------------------------------------- |
    | `language`  | `en-US`  | Language code                                 |
    | `model`     | `nova-3` | Model: `nova-2`, `nova-3`, `base`, `enhanced` |
    | `punctuate` | `true`   | Add punctuation                               |
    | `diarize`   | `true`   | Speaker diarization                           |
  </Step>
</Steps>

***

## How It Works

```go theme={null}
// Initialize: opens WebSocket to Deepgram live transcription endpoint
d.client = client.NewWSUsingCallback(liveTranscriptionOptions)
d.client.Connect()

// Transform: streams raw PCM bytes
d.client.Stream(bufio.NewReader(bytes.NewReader(in.Audio)))

// Close: graceful stop
d.client.Stop()
```

***

<CardGroup>
  <Card title="Deepgram TTS" icon="volume" href="/opensource/services/assistant-api/tts/deepgram">
    Deepgram Aura text-to-speech
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers and transformer interface
  </Card>
</CardGroup>


# Google Cloud STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/google

Configure Google Cloud Speech-to-Text in assistant-api.

Google Cloud Speech-to-Text provides real-time streaming transcription with support for 100+ languages.

**Provider identifier:** `google-speech-service`

***

## Vault Credential

| Key   | Description                                    |
| ----- | ---------------------------------------------- |
| `key` | Google Cloud service account JSON (or API key) |

***

## Setup

<Steps>
  <Step title="Create a Google Cloud service account">
    In [Google Cloud Console](https://console.cloud.google.com) → **IAM & Admin → Service Accounts**, create a service account with the **Cloud Speech-to-Text User** role. Download the JSON key file.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Google**, paste the service account JSON as the value of `key`.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Google Speech**.

    | Option     | Example       | Description                                                 |
    | ---------- | ------------- | ----------------------------------------------------------- |
    | `language` | `en-US`       | BCP-47 language code                                        |
    | `model`    | `latest_long` | Model: `latest_short`, `latest_long`, `phone_call`, `video` |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Google Cloud TTS" icon="volume" href="/opensource/services/assistant-api/tts/google">
    Google Cloud text-to-speech
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Groq STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/groq

Configure Groq speech-to-text with ultra-fast Whisper inference in assistant-api.

Groq provides speech-to-text via an OpenAI Whisper-compatible HTTP API, accelerated by its LPU inference engine for extremely fast transcription. It is well-suited for real-time voice assistant pipelines that require near-instant transcripts.

**Provider identifier:** `groq`

***

## Vault Credential

| Key   | Description                                            |
| ----- | ------------------------------------------------------ |
| `key` | Groq API key from [groq.com](https://console.groq.com) |

***

## Setup

<Steps>
  <Step title="Get a Groq API key">
    Sign in at [console.groq.com](https://console.groq.com) → **API Keys → Create API Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Groq**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Groq**.

    | Option     | Example                  | Description                                                                                                                           |
    | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
    | `model`    | `whisper-large-v3-turbo` | Model: `whisper-large-v3-turbo` (fast), `whisper-large-v3` (highest accuracy)                                                         |
    | `language` | `en`                     | ISO-639-1 language code: `en`, `es`, `fr`, `de`, `it`, `pt`, `ja`, `zh`, `ar`, and more. Leave blank for automatic language detection |

    See supported models and languages in the [Groq STT documentation](https://console.groq.com/docs/speech-text).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Groq TTS" icon="microphone" href="/opensource/services/assistant-api/tts/groq">
    Groq text-to-speech with PlayAI
  </Card>

  <Card title="STT Overview" icon="waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# NVIDIA STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/nvidia

Configure NVIDIA speech-to-text via the NVCF API in assistant-api.

NVIDIA provides speech-to-text through the NVIDIA Cloud Functions (NVCF) API, offering enterprise-grade automatic speech recognition powered by NVIDIA's inference infrastructure.

**Provider identifier:** `nvidia`

***

## Vault Credentials

| Key           | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `key`         | NVIDIA API key from [nvidia.com](https://build.nvidia.com) |
| `function_id` | NVCF Function ID for the STT model endpoint                |

***

## Setup

<Steps>
  <Step title="Get NVIDIA API credentials">
    Sign in at [build.nvidia.com](https://build.nvidia.com) → **API Keys** to generate your API key. Navigate to the desired ASR model card in the NIM catalog to find the corresponding NVCF Function ID.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **NVIDIA**, enter `key` = your API key and `function_id` = your NVCF Function ID.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **NVIDIA**.

    | Option     | Example | Description                                                                   |
    | ---------- | ------- | ----------------------------------------------------------------------------- |
    | `language` | `en-US` | Language code: `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, and more |

    Browse available ASR models and supported languages in the [NVIDIA NIM catalog](https://build.nvidia.com/explore/speech).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="NVIDIA TTS" icon="microphone" href="/opensource/services/assistant-api/tts/nvidia">
    NVIDIA text-to-speech via NVCF
  </Card>

  <Card title="STT Overview" icon="waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Speech-to-Text — Overview
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/overview

STT transformer interface, factory functions, and supported providers in assistant-api.

The `assistant-api` decouples audio transcription from provider-specific logic through a **transformer layer**. Every STT provider implements the same generic interface. The factory resolves the provider string at call time.

***

## Transformer Interface

Every STT provider implements `Transformers[UserAudioPacket]`:

```go theme={null}
// api/assistant-api/internal/type/transformer.go
type Transformers[IN any] interface {
    // Initialize sets up the provider connection (WebSocket, gRPC, HTTP client).
    // Called once per call session before audio begins.
    Initialize() error

    // Transform sends one audio packet to the provider.
    // Transcription results are delivered via the onPacket callback registered at construction.
    Transform(ctx context.Context, in IN) error

    // Close tears down the connection and releases resources.
    Close(ctx context.Context) error
}

// Type alias for STT
type SpeechToTextTransformer = Transformers[UserAudioPacket]
```

`UserAudioPacket.Audio` contains raw **PCM 16-bit mono 16kHz** bytes. All providers receive this same format — resampling from 8kHz telephony audio is handled upstream.

***

## Factory Function

```go theme={null}
// api/assistant-api/internal/transformer/transformer.go
func GetSpeechToTextTransformer(
    ctx        context.Context,
    logger     commons.Logger,
    provider   string,                     // AudioTransformer constant string
    credential *protos.VaultCredential,    // decrypted vault credential
    onPacket   func(STTPacket),            // callback invoked with each transcript result
    opts       utils.Option,               // assistant-level options (language, model, etc.)
) (SpeechToTextTransformer, error)
```

The factory switches on the `provider` string. To add a new provider, add a case to this switch.

***

## Provider Identifiers

```go theme={null}
// api/assistant-api/internal/transformer/transformer.go
const (
    DEEPGRAM              AudioTransformer = "deepgram"
    GOOGLE_SPEECH_SERVICE AudioTransformer = "google-speech-service"
    AZURE_SPEECH_SERVICE  AudioTransformer = "azure-speech-service"
    CARTESIA              AudioTransformer = "cartesia"
    REVAI                 AudioTransformer = "revai"
    SARVAM                AudioTransformer = "sarvamai"
    ELEVENLABS            AudioTransformer = "elevenlabs"
    ASSEMBLYAI            AudioTransformer = "assemblyai"
)
```

***

## Supported STT Providers

| Provider             | Identifier              | Streaming | Notes                                            |
| -------------------- | ----------------------- | --------- | ------------------------------------------------ |
| **Deepgram**         | `deepgram`              | ✅         | Nova-2 / Nova-3, WebSocket SDK                   |
| **Google Cloud STT** | `google-speech-service` | ✅         | 100+ languages                                   |
| **Azure Cognitive**  | `azure-speech-service`  | ✅         | Neural Speech, 140+ languages                    |
| **AssemblyAI**       | `assemblyai`            | ✅         | Speaker diarization                              |
| **Rev.ai**           | `revai`                 | ✅         | Real-time                                        |
| **Sarvam AI**        | `sarvamai`              | ✅         | Indian languages                                 |
| **Smallest AI**      | `smallest`              | ✅         | Pulse, 64ms TTFT, diarization, PII/PCI redaction |
| **AWS Transcribe**   | `aws`                   | ✅         | Real-time streaming                              |
| **OpenAI Whisper**   | `openai`                | ✗         | Batch only                                       |
| **Speechmatics**     | `speechmatics`          | ✅         | Real-time                                        |

***

## Provider Pages

<CardGroup>
  <Card title="Deepgram" icon="audio-waveform" href="/opensource/services/assistant-api/stt/deepgram">
    Nova-2/Nova-3, WebSocket streaming
  </Card>

  <Card title="Google Cloud" icon="globe" href="/opensource/services/assistant-api/stt/google">
    100+ languages, Neural Speech
  </Card>

  <Card title="Azure" icon="cloud" href="/opensource/services/assistant-api/stt/azure">
    Neural Speech, 140+ languages
  </Card>

  <Card title="AssemblyAI" icon="activity" href="/opensource/services/assistant-api/stt/assemblyai">
    Speaker diarization, real-time
  </Card>

  <Card title="Rev.ai" icon="audio-waveform" href="/opensource/services/assistant-api/stt/revai">
    Real-time streaming
  </Card>

  <Card title="Sarvam AI" icon="languages" href="/opensource/services/assistant-api/stt/sarvamai">
    Indian languages
  </Card>

  <Card title="Smallest AI" icon="zap" href="/opensource/services/assistant-api/stt/smallest">
    Pulse, 64ms TTFT, diarization, redaction
  </Card>

  <Card title="Custom STT" icon="code" href="/opensource/services/assistant-api/stt/custom">
    Configure WebSocket or HTTP STT with DSL rules
  </Card>
</CardGroup>


# Rev.ai STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/revai

Configure Rev.ai real-time speech-to-text in assistant-api.

Rev.ai provides real-time streaming speech recognition with a focus on accuracy.

**Provider identifier:** `revai`

***

## Vault Credential

| Key   | Description                                                                      |
| ----- | -------------------------------------------------------------------------------- |
| `key` | Rev.ai access token from [rev.ai/access\_token](https://www.rev.ai/access_token) |

***

## Setup

<Steps>
  <Step title="Get a Rev.ai access token">
    Sign in at [rev.ai](https://www.rev.ai) → **Access Tokens → Generate Access Token**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Rev.ai**, enter `key` = your access token.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Rev.ai**.

    | Option     | Example        | Description           |
    | ---------- | -------------- | --------------------- |
    | `language` | `en`           | Language code         |
    | `metadata` | `call-session` | Optional metadata tag |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Deepgram" icon="audio-waveform" href="/opensource/services/assistant-api/stt/deepgram">
    Alternative low-latency STT
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Sarvam AI STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/sarvamai

Configure Sarvam AI speech-to-text for Indian languages in assistant-api.

Sarvam AI specialises in Indian languages — Hindi, Bengali, Telugu, Tamil, Kannada, Malayalam, Marathi, Gujarati, Punjabi, and more.

**Provider identifier:** `sarvamai`

***

## Vault Credential

| Key   | Description                                                               |
| ----- | ------------------------------------------------------------------------- |
| `key` | Sarvam AI API key from [dashboard.sarvam.ai](https://dashboard.sarvam.ai) |

***

## Setup

<Steps>
  <Step title="Get a Sarvam AI API key">
    Sign in at [dashboard.sarvam.ai](https://dashboard.sarvam.ai) → **API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Sarvam AI**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Sarvam AI**.

    | Option     | Example      | Description                               |
    | ---------- | ------------ | ----------------------------------------- |
    | `language` | `hi-IN`      | BCP-47 language code (Hindi, Tamil, etc.) |
    | `model`    | `saarika:v1` | Sarvam model variant                      |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Sarvam AI TTS" icon="volume" href="/opensource/services/assistant-api/tts/sarvamai">
    Sarvam AI text-to-speech for Indian languages
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Smallest AI STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/smallest

Configure Smallest AI Pulse speech-to-text in assistant-api.

Smallest AI's Pulse model streams over a realtime WebSocket with 64ms time-to-first-transcript, supporting 38 languages plus word/sentence-level timestamps, speaker diarization, and PII/PCI redaction.

**Provider identifier:** `smallest`

***

## Vault Credential

| Key   | Description                                                                             |
| ----- | --------------------------------------------------------------------------------------- |
| `key` | Smallest AI API key from [app.smallest.ai/dashboard](https://app.smallest.ai/dashboard) |

***

## Setup

<Steps>
  <Step title="Get a Smallest AI API key">
    Sign in at [app.smallest.ai/dashboard](https://app.smallest.ai/dashboard) → **Developer → API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Providers and Models**, add a credential, select provider **Smallest AI**, enter `key` = your API key.

    The same credential is used for both Smallest AI STT and TTS.
  </Step>

  <Step title="Configure the assistant">
    In the assistant's deployment settings → **Audio Input (STT)**, select **Smallest AI**.

    | Option                       | Example | Description                                                                          |
    | ---------------------------- | ------- | ------------------------------------------------------------------------------------ |
    | `listen.model`               | `pulse` | Only `pulse` is wired to the realtime endpoint — Pulse Pro is pre-recorded/HTTP only |
    | `listen.language`            | `en`    | ISO language code, or omit for auto-detect across 38 languages                       |
    | `listen.word_timestamps`     | `true`  | Per-word start/end/confidence timing                                                 |
    | `listen.sentence_timestamps` | `true`  | Sentence-level utterance segments                                                    |
    | `listen.diarize`             | `true`  | Speaker labels on words/utterances                                                   |
    | `listen.redact_pii`          | `true`  | Redacts names, addresses, phone numbers as `[ENTITYTYPE_N]` placeholders             |
    | `listen.redact_pci`          | `true`  | Redacts card numbers, CVVs, ZIP codes, account numbers                               |
    | `listen.numerals`            | `auto`  | Inverse text normalization mode                                                      |
    | `listen.smart_format`        | `true`  | Punctuation/capitalization in the transcript (defaults to `true` server-side)        |

    All feature flags are opt-in — omitted entirely from the connection string unless explicitly set.
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Smallest AI TTS" icon="volume" href="/opensource/services/assistant-api/tts/smallest">
    Smallest AI Lightning text-to-speech
  </Card>

  <Card title="STT Overview" icon="audio-waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Speechmatics STT
Source: https://doc.rapida.ai/opensource/services/assistant-api/stt/speechmatics

Configure Speechmatics real-time speech-to-text with WebSocket streaming in assistant-api.

Speechmatics provides real-time speech recognition via WebSocket streaming with broad language coverage and strong accuracy across diverse accents and audio conditions. It is well-suited for multilingual voice assistant deployments.

**Provider identifier:** `speechmatics`

***

## Vault Credential

| Key   | Description                                                                   |
| ----- | ----------------------------------------------------------------------------- |
| `key` | Speechmatics API key from [speechmatics.com](https://portal.speechmatics.com) |

***

## Setup

<Steps>
  <Step title="Get a Speechmatics API key">
    Sign in at [portal.speechmatics.com](https://portal.speechmatics.com) → **API Keys → Generate API Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Speechmatics**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **STT Provider**, select **Speechmatics**.

    | Option     | Example | Description                                                                                   |
    | ---------- | ------- | --------------------------------------------------------------------------------------------- |
    | `language` | `en`    | Language code: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ja`, `zh`, `ar`, and 40+ more |

    See the full language list in the [Speechmatics language support documentation](https://docs.speechmatics.com/introduction/supported-languages).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Speechmatics TTS" icon="microphone" href="/opensource/services/assistant-api/tts/speechmatics">
    Speechmatics text-to-speech
  </Card>

  <Card title="STT Overview" icon="waveform" href="/opensource/services/assistant-api/stt/overview">
    All STT providers
  </Card>
</CardGroup>


# Assistant API — Telemetry
Source: https://doc.rapida.ai/opensource/services/assistant-api/telemetry

UI setup, runtime wiring, provider options, and telemetry query behavior for assistant-api.

## Scope

| Area                             | Implemented in                                                                         |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| Configure telemetry in UI        | `ui/src/app/pages/assistant/actions/configure-assistant-telemetry/*`                   |
| Provider form/default/validation | `ui/src/app/components/providers/telemetry/*`                                          |
| Provider registry                | `ui/src/providers/index.ts`, `ui/src/providers/provider.*.json`                        |
| Provider CRUD API                | `api/assistant-api/api/assistant/*assistant_telemetry_provider*.go`                    |
| Runtime collector init           | `api/assistant-api/internal/adapters/internal/requestor.go`                            |
| Exporter factory                 | `api/assistant-api/internal/observe/exporters/factory.go`, `pkg/telemetry/providers/*` |
| Conversation telemetry read API  | `api/assistant-api/api/assistant/get_all_assistant_telemetry.go`                       |

***

## Configure Assistant Telemetry (UI)

| Route                                                                 | Purpose                                |
| --------------------------------------------------------------------- | -------------------------------------- |
| `/deployment/assistant/:assistantId/configure-telemetry`              | List telemetry providers for assistant |
| `/deployment/assistant/:assistantId/configure-telemetry/create`       | Create provider                        |
| `/deployment/assistant/:assistantId/configure-telemetry/:telemetryId` | Update provider                        |

UI store and API calls:

| Action            | API                                |
| ----------------- | ---------------------------------- |
| List providers    | `GetAllAssistantTelemetryProvider` |
| Create provider   | `CreateAssistantTelemetryProvider` |
| Read one provider | `GetAssistantTelemetryProvider`    |
| Update provider   | `UpdateAssistantTelemetryProvider` |
| Delete provider   | `DeleteAssistantTelemetryProvider` |

***

## UI Provider Support

### Provider list shown in UI

| Provider code   | Visible in UI |
| --------------- | ------------- |
| `otlp_http`     | Yes           |
| `datadog`       | Yes           |
| `xray`          | Yes           |
| `google_trace`  | Yes           |
| `azure_monitor` | Yes           |

### Backend-supported exporter types

| Provider code   | Supported by backend |
| --------------- | -------------------- |
| `otlp_http`     | Yes                  |
| `otlp_grpc`     | Yes                  |
| `xray`          | Yes                  |
| `google_trace`  | Yes                  |
| `azure_monitor` | Yes                  |
| `datadog`       | Yes                  |
| `opensearch`    | Yes                  |
| `logging`       | Yes                  |

`provider-telemetry.test.ts` verifies UI registry parity and `telemetry.json` presence for UI-visible telemetry providers.

***

## UI Form Rules

| Rule                | Behavior                                                           |
| ------------------- | ------------------------------------------------------------------ |
| Credential required | `rapida.credential_id` must be present                             |
| Provider defaults   | Loaded from `ui/src/providers/<provider>/telemetry.json`           |
| Required fields     | Validated against `telemetry.json` parameter definitions           |
| On provider switch  | Keeps only credential, then applies defaults for selected provider |

### `telemetry.json` parameters used in UI

| Provider        | Parameters in JSON                 |
| --------------- | ---------------------------------- |
| `otlp_http`     | `endpoint`, `protocol`, `insecure` |
| `datadog`       | `endpoint`, `insecure`             |
| `xray`          | `endpoint`, `region`, `insecure`   |
| `google_trace`  | `endpoint`, `insecure`             |
| `azure_monitor` | `endpoint`, `insecure`             |

***

## Assistant Telemetry Provider Data Model

Migration: `api/assistant-api/migrations/000008_assistant_telemetry_providers.up.sql`

| Table                                  | Purpose                               |
| -------------------------------------- | ------------------------------------- |
| `assistant_telemetry_providers`        | one provider attachment per assistant |
| `assistant_telemetry_provider_options` | flat key/value options per provider   |

Update behavior in service (`telemetry.impl.service.go`):

| Step                | Behavior                           |
| ------------------- | ---------------------------------- |
| Update provider row | updates `provider_type`, `enabled` |
| Existing options    | archived (`status = archieve`)     |
| New options         | inserted as active rows            |

***

## Runtime Wiring in assistant-api

Runtime collector initialization happens in `initializeCollectors()`.

| Stage                   | Behavior                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Load providers          | reads `AssistantTelemetryProviders` from assistant state                                     |
| Session metadata        | sets assistant/conversation/project/org IDs                                                  |
| Env exporter (optional) | creates one exporter from `TELEMETRY__TYPE` + provider config                                |
| Credential merge        | if `rapida.credential_id` exists, loads vault credential and merges string keys into options |
| Exporter creation       | resolves provider via exporter factory                                                       |
| Collector build         | creates fan-out event + metric collectors                                                    |

Only `enabled = true` providers are injected when assistant is loaded (`assistant.impl.service.go`).

***

## Exporter Option Parsing Rules

Option parsing code: `pkg/telemetry/providers/config.go`

| Provider                  | Required                                                   | Optional keys                                    |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------ |
| `otlp_http` / `otlp_grpc` | `endpoint` (effectively required; nil exporter if missing) | `protocol`, `headers`, `insecure`                |
| `datadog`                 | `endpoint`                                                 | `protocol`, `headers`, `api_key`, `insecure`     |
| `xray`                    | `endpoint`                                                 | `protocol`, `region`, `insecure`                 |
| `google_trace`            | `endpoint`                                                 | `headers`, `api_key`, `access_token`, `insecure` |
| `azure_monitor`           | `endpoint`                                                 | `headers`, `api_key`, `insecure`                 |
| `opensearch`              | none                                                       | `index_prefix`                                   |
| `logging`                 | none                                                       | none                                             |

Common parser behavior:

| Key        | Behavior                                   |
| ---------- | ------------------------------------------ |
| `headers`  | accepts comma-separated `key=value` string |
| `insecure` | accepts `true` / `1`                       |

***

## Conversation Telemetry Read API

API: `GetAllAssistantTelemetry`

| Source index       | Mapped record     |
| ------------------ | ----------------- |
| `rapida-events-*`  | `TelemetryEvent`  |
| `rapida-metrics-*` | `TelemetryMetric` |

Supported filters from criteria:

| Criteria key     | Applied to                                    |
| ---------------- | --------------------------------------------- |
| `conversationId` | event + metric query                          |
| `messageId`      | `messageId` in events, `contextId` in metrics |
| `name`           | events                                        |
| `scope`          | metrics                                       |

Pagination behavior:

| Input              | Behavior      |
| ------------------ | ------------- |
| page \< 1          | coerced to 1  |
| size \< 1 or > 100 | coerced to 20 |

UI consumer for this API:

* `ui/src/app/components/base/modal/conversation-telemetry-modal/index.tsx`


# Asterisk
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/asterisk

Run assistant-api with Asterisk PBX using AudioSocket (native TCP) or WebSocket transport.

Asterisk integrates with Rapida using two transport methods. Choose based on your Asterisk version and network topology.

## Transport Comparison

|                      | AudioSocket                    | WebSocket                 |
| -------------------- | ------------------------------ | ------------------------- |
| **Asterisk version** | 16+                            | 20+                       |
| **Module**           | `res_audiosocket`              | `chan_websocket`          |
| **Protocol**         | Raw TCP port 4573              | WSS (standard HTTPS port) |
| **Firewall**         | TCP 4573 must be open outbound | Standard HTTPS only       |
| **Audio codec**      | SLIN 16-bit 8kHz               | μ-law 8kHz                |
| **Latency**          | Lowest                         | Slightly higher           |
| **TLS**              | No                             | Yes (native WSS)          |
| **Best for**         | LAN / private network          | Cloud / NAT traversal     |

***

## AudioSocket

<Steps>
  <Step title="Configure env vars">
    ```env theme={null}
    # docker/assistant-api/.assistant.env
    PUBLIC_ASSISTANT_HOST=your-hostname.com
    AUDIOSOCKET__HOST=0.0.0.0
    AUDIOSOCKET__PORT=4573
    ```

    `assistant-api` binds a TCP AudioSocket server on `AUDIOSOCKET__PORT` at startup.
  </Step>

  <Step title="Verify the module is loaded">
    ```bash theme={null}
    asterisk -rx "module show like audiosocket"
    # Expected: res_audiosocket.so
    ```

    If not loaded, add to `/etc/asterisk/modules.conf`:

    ```ini theme={null}
    [modules]
    load = res_audiosocket.so
    ```
  </Step>

  <Step title="Configure the dialplan">
    ```ini theme={null}
    # /etc/asterisk/extensions.conf

    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = {PUBLIC_ASSISTANT_HOST}   ; HTTP/webhook host (HTTPS)
    RAPIDA_AS_HOST = {PUBLIC_ASSISTANT_HOST}   ; AudioSocket TCP host
    RAPIDA_PORT    = 4573
    ASSISTANT_ID   = 123456789

    [rapida-inbound]
    exten => _X.,1,Answer()
     same => n,Set(CHANNEL(audioreadformat)=slin)
     same => n,Set(CHANNEL(audiowriteformat)=slin)
     ; Phase 1 — register the call and get a contextId
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     ; Phase 2 — open AudioSocket TCP using contextId as UUID
     same => n,AudioSocket(${CTX},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()
    ```

    <Warning>
      `CHANNEL(audioreadformat)=slin` and `CHANNEL(audiowriteformat)=slin` are required. AudioSocket expects SLIN (signed linear PCM) — without this Asterisk will not convert the audio format.
    </Warning>
  </Step>

  <Step title="Reload and test">
    ```bash theme={null}
    asterisk -rx "dialplan reload"

    # Verify connectivity
    nc -zv {RAPIDA_AS_HOST} 4573    # AudioSocket TCP
    curl -I https://{RAPIDA_HOST}   # HTTPS webhook
    ```
  </Step>
</Steps>

### Outbound via ARI (AudioSocket)

For outbound calls, Rapida uses Asterisk's ARI to originate the channel. The `RAPIDA_CONTEXT_ID` channel variable is injected by Rapida ARI automatically:

```ini theme={null}
; /etc/asterisk/extensions.conf
[rapida-outbound]
exten => s,1,Set(CHANNEL(audioreadformat)=slin)
 same => n,Set(CHANNEL(audiowriteformat)=slin)
 ; RAPIDA_CONTEXT_ID is set by Rapida ARI when originating the call
 same => n,AudioSocket(${RAPIDA_CONTEXT_ID},${RAPIDA_AS_HOST}:${RAPIDA_PORT})
 same => n,Hangup()
```

**ARI vault credential keys** (store in Rapida vault, provider type **Asterisk**):

| Key                   | Required | Description                                     |
| --------------------- | -------- | ----------------------------------------------- |
| `ari_url`             | Yes      | ARI base URL, e.g. `http://asterisk.local:8088` |
| `ari_user`            | Yes      | ARI username                                    |
| `ari_password`        | Yes      | ARI password                                    |
| `endpoint_technology` | No       | Channel technology — default `PJSIP`            |
| `trunk`               | No       | SIP trunk name — builds `PJSIP/trunk/number`    |

***

## WebSocket

<Steps>
  <Step title="Configure env vars">
    ```env theme={null}
    # docker/assistant-api/.assistant.env
    PUBLIC_ASSISTANT_HOST=your-hostname.com
    # No AudioSocket port needed — WebSocket uses standard HTTPS
    ```
  </Step>

  <Step title="Verify the module is loaded">
    ```bash theme={null}
    asterisk -rx "module show like chan_websocket"
    # Expected: chan_websocket.so — requires Asterisk 20+
    ```

    If not loaded, add to `/etc/asterisk/modules.conf`:

    ```ini theme={null}
    [modules]
    load = chan_websocket.so
    ```
  </Step>

  <Step title="Configure the dialplan">
    ```ini theme={null}
    # /etc/asterisk/extensions.conf

    [globals]
    RAPIDA_API_KEY = rpd-xxx-your-api-key
    RAPIDA_HOST    = {PUBLIC_ASSISTANT_HOST}
    ASSISTANT_ID   = 123456789

    [rapida-inbound-ws]
    exten => _X.,1,Answer()
     ; Phase 1 — register the call and get a contextId
     same => n,Set(CTX=${CURL(https://${RAPIDA_HOST}/v1/talk/asterisk/call/${ASSISTANT_ID}?from=${CALLERID(num)}&x-api-key=${RAPIDA_API_KEY})})
     same => n,GotoIf($["${CTX}" = ""]?error)
     ; Phase 2 — open WSS connection with contextId in the URL path
     same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${CTX}?x-api-key=${RAPIDA_API_KEY})
     same => n,Hangup()
     same => n(error),Playback(an-error-has-occurred)
     same => n,Hangup()
    ```
  </Step>

  <Step title="Reload and test">
    ```bash theme={null}
    asterisk -rx "dialplan reload"
    curl -I https://{RAPIDA_HOST}
    ```
  </Step>
</Steps>

### Outbound via ARI (WebSocket)

```ini theme={null}
; /etc/asterisk/extensions.conf
[rapida-outbound-ws]
exten => s,1,NoOp(Outbound WebSocket call)
 ; RAPIDA_CONTEXT_ID is set by Rapida ARI
 same => n,WebSocket(wss://${RAPIDA_HOST}/v1/talk/asterisk/ctx/${RAPIDA_CONTEXT_ID}?x-api-key=${RAPIDA_API_KEY})
 same => n,Hangup()
```

Same ARI vault credentials apply — see the AudioSocket section.

***

## Production URLs

For Rapida SaaS:

| Variable                           | Value                       |
| ---------------------------------- | --------------------------- |
| `RAPIDA_HOST` (HTTP/WebSocket)     | `websocket-01.in.rapida.ai` |
| `RAPIDA_AS_HOST` (AudioSocket TCP) | `socket-01.in.rapida.ai`    |
| `RAPIDA_PORT`                      | `4573`                      |

***

<CardGroup>
  <Card title="SIP" icon="signal" href="/opensource/services/assistant-api/telephony/sip">
    Built-in SIP server for direct SIP connectivity
  </Card>

  <Card title="Configure Your Own" icon="code" href="/opensource/services/assistant-api/telephony/custom">
    Add a new telephony provider
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    AUDIOSOCKET env vars reference
  </Card>

  <Card title="Telephony Overview" icon="network" href="/opensource/services/assistant-api/telephony/overview">
    All providers comparison
  </Card>
</CardGroup>


# Configure Your Own Telephony Provider
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/custom

Implement the Telephony and Streamer interfaces to add a new telephony provider to assistant-api.

Every telephony provider in Rapida implements two Go interfaces. Adding a new one requires implementing both, registering them in the factory, and adding a provider constant.

***

## Directory Structure

```
api/assistant-api/internal/channel/telephony/internal/<provider>/
├── telephony.go   # Telephony interface — webhook handling, outbound call origination
└── websocket.go   # Streamer interface — bridges media stream to AI pipeline
```

***

## Step 1 — Add the Provider Constant

Open `api/assistant-api/internal/channel/telephony/telephony.go`:

```go theme={null}
const (
    Twilio     Telephony = "twilio"
    // ... existing constants ...
    MyProvider Telephony = "my-provider"  // add this
)
```

This string becomes the provider identifier in all webhook URLs:
`/v1/talk/my-provider/call/{assistantId}`

***

## Step 2 — Implement `internal_type.Telephony`

```go theme={null}
// api/assistant-api/internal/channel/telephony/internal/myprovider/telephony.go
package myprovider

type myProviderTelephony struct {
    cfg    interface{}
    logger *zap.SugaredLogger
}

func NewMyProviderTelephony(cfg interface{}, logger *zap.SugaredLogger) internal_type.Telephony {
    return &myProviderTelephony{cfg: cfg, logger: logger}
}

// ReceiveCall handles POST /v1/talk/my-provider/call/{assistantId}
// Return StatusInfo containing contextId — Rapida stores it and generates the media URL.
func (t *myProviderTelephony) ReceiveCall(c *gin.Context) (*internal_type.StatusInfo, error) {
    assistantId := c.Param("assistantId")
    from := c.Query("from")
    // Build and return StatusInfo; Rapida handles contextId creation
    _ = assistantId
    _ = from
    return nil, nil
}

// OutboundCall initiates a call to toPhone using the provider's API.
// vaultCred contains the decrypted credential map from the Rapida vault.
func (t *myProviderTelephony) OutboundCall(
    auth, toPhone, fromPhone string,
    cc internal_type.Communication,
    vaultCred map[string]interface{},
    opts internal_type.CallOptions,
) (*internal_type.CallInfo, error) {
    apiKey := vaultCred["key"].(string)
    _ = apiKey
    return nil, nil
}

// InboundCall handles the WebSocket upgrade at /v1/talk/my-provider/ctx/{contextId}
func (t *myProviderTelephony) InboundCall(c *gin.Context, cc internal_type.Communication) error {
    return nil
}

// StatusCallback handles POST /v1/talk/my-provider/ctx/{contextId}/event
func (t *myProviderTelephony) StatusCallback(
    c *gin.Context, cc internal_type.Communication,
) (*internal_type.StatusInfo, error) {
    return nil, nil
}

// CatchAllStatusCallback handles unmatched status events
func (t *myProviderTelephony) CatchAllStatusCallback(c *gin.Context) (*internal_type.StatusInfo, error) {
    return nil, nil
}
```

***

## Step 3 — Implement `internal_type.Streamer`

```go theme={null}
// api/assistant-api/internal/channel/telephony/internal/myprovider/websocket.go
package myprovider

type myProviderStreamer struct {
    conn      *websocket.Conn
    cc        internal_type.Communication
    vaultCred map[string]interface{}
    logger    *zap.SugaredLogger
}

func NewMyProviderStreamer(
    logger *zap.SugaredLogger,
    conn *websocket.Conn,
    cc internal_type.Communication,
    vaultCred map[string]interface{},
) internal_type.Streamer {
    return &myProviderStreamer{conn: conn, cc: cc, vaultCred: vaultCred, logger: logger}
}

// Stream runs the bidirectional audio loop — blocks until the call ends.
func (s *myProviderStreamer) Stream(ctx context.Context) error {
    // 1. Read audio frames from s.conn (format depends on provider — JSON envelope or raw binary)
    // 2. Decode audio to raw PCM (μ-law → PCM or base64 decode as needed)
    // 3. Forward to s.cc.StreamAudio(ctx, audioBytes)
    // 4. Listen on s.cc.OnResponse() for TTS audio and write back to s.conn
    return nil
}

func (s *myProviderStreamer) Close() error {
    return s.conn.Close()
}
```

**Audio format notes:**

* Rapida's STT pipeline expects raw PCM 16-bit mono
* Twilio and Exotel send base64-encoded μ-law 8kHz in JSON envelopes — decode before forwarding
* Vonage sends raw Linear PCM 16kHz binary frames

***

## Step 4 — Register in the Factory

Open `api/assistant-api/internal/channel/telephony/telephony.go`:

```go theme={null}
func GetTelephony(at Telephony, cfg, logger, opts) (internal_type.Telephony, error) {
    switch at {
    case Twilio:
        return internal_twilio.NewTwilioTelephony(cfg, logger), nil
    // ... existing cases ...
    case MyProvider:
        return internal_myprovider.NewMyProviderTelephony(cfg, logger), nil  // add this
    default:
        return nil, fmt.Errorf("unsupported telephony provider: %s", at)
    }
}

func (at Telephony) NewStreamer(logger, cc, vaultCred, opt) (internal_type.Streamer, error) {
    switch at {
    case Twilio:
        return internal_twilio.NewTwilioStreamer(logger, opt.WebSocketConn, cc, vaultCred), nil
    // ... existing cases ...
    case MyProvider:
        return internal_myprovider.NewMyProviderStreamer(logger, opt.WebSocketConn, cc, vaultCred), nil  // add this
    default:
        return nil, fmt.Errorf("unsupported telephony streamer: %s", at)
    }
}
```

***

## Step 5 — Rebuild

```bash theme={null}
make rebuild-assistant
make logs-assistant
```

The new provider's webhook is automatically registered at:

```
POST /v1/talk/my-provider/call/{assistantId}
```

***

## Reference Implementations

| Provider | Directory            | Pattern                                     |
| -------- | -------------------- | ------------------------------------------- |
| Twilio   | `internal/twilio/`   | JSON envelope, base64 μ-law, TwiML response |
| Vonage   | `internal/vonage/`   | NCCO JSON, binary PCM frames                |
| Asterisk | `internal/asterisk/` | Two-phase HTTP + ARI outbound               |
| SIP      | `internal/sip/`      | Direct UDP, RTP media                       |

***

<CardGroup>
  <Card title="Telephony Overview" icon="phone" href="/opensource/services/assistant-api/telephony/overview">
    URL routing and provider comparison
  </Card>

  <Card title="Adding an STT Provider" icon="mic" href="/opensource/services/assistant-api/stt/custom">
    Same interface pattern for speech-to-text
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    All assistant-api env vars
  </Card>

  <Card title="Architecture" icon="network" href="/opensource/architecture">
    Full system topology
  </Card>
</CardGroup>


# Exotel
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/exotel

Run assistant-api with Exotel for PSTN voice calls in India and South-East Asia.

Exotel is a cloud telephony provider for India and South-East Asia. It follows the same webhook → WebSocket pattern as Twilio: Exotel calls your server when a call arrives, Rapida responds with passthru XML that opens a WebSocket media stream.

***

## Vault Credentials

In the Rapida dashboard go to **Credentials → Create Credential**, select provider type **Exotel**:

| Key           | Description        |
| ------------- | ------------------ |
| `api_key`     | Exotel API key     |
| `api_secret`  | Exotel API secret  |
| `account_sid` | Exotel Account SID |

***

## Setup

<Steps>
  <Step title="Set PUBLIC_ASSISTANT_HOST">
    `PUBLIC_ASSISTANT_HOST` is the public HTTPS hostname Exotel will use to reach your server — for webhooks and the WebSocket media stream.

    <Tabs>
      <Tab title="Production">
        Set it in `docker/assistant-api/.assistant.env`:

        ```env theme={null}
        PUBLIC_ASSISTANT_HOST=your-server.com   # no https:// prefix
        ```

        Also update `connection.media` in `ui/src/configs/config.production.json`:

        ```json theme={null}
        {
          "connection": {
            "media": "https://your-server.com"
          }
        }
        ```
      </Tab>

      <Tab title="Local Development (ngrok)">
        Exotel's servers originate from India/SEA and cannot reach `localhost`. Use ngrok to create a public HTTPS tunnel:

        **1. Install and authenticate ngrok**

        ```bash theme={null}
        # macOS
        brew install ngrok/ngrok/ngrok

        # Linux
        curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
          | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
        echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
          | sudo tee /etc/apt/sources.list.d/ngrok.list
        sudo apt update && sudo apt install ngrok

        ngrok config add-authtoken <your-authtoken>
        ```

        Get your authtoken at [dashboard.ngrok.com](https://dashboard.ngrok.com/get-started/your-authtoken).

        **2. Start the tunnel** (keep this running)

        ```bash theme={null}
        ngrok http 8080
        # Forwarding  https://abc123.ngrok-free.app -> http://localhost:8080
        ```

        **3. Update two files with the ngrok hostname**

        | File                                     | Field                   | Value                                               |
        | ---------------------------------------- | ----------------------- | --------------------------------------------------- |
        | `docker/assistant-api/.assistant.env`    | `PUBLIC_ASSISTANT_HOST` | `abc123.ngrok-free.app` *(no `https://`)*           |
        | `ui/src/configs/config.development.json` | `connection.media`      | `https://abc123.ngrok-free.app` *(with `https://`)* |

        ```env theme={null}
        # docker/assistant-api/.assistant.env
        PUBLIC_ASSISTANT_HOST=abc123.ngrok-free.app
        ```

        ```json theme={null}
        // ui/src/configs/config.development.json
        {
          "connection": {
            "media": "https://abc123.ngrok-free.app"
          }
        }
        ```

        **4. Rebuild**

        ```bash theme={null}
        make rebuild-assistant
        ```

        <Note>
          Exotel may have higher latency to ngrok tunnels depending on region. For best results during testing, use an ngrok region closest to Exotel's traffic origin (India): `ngrok http 8080 --region=in` (if available on your plan).
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the ExoPhone app">
    In [Exotel Dashboard](https://my.exotel.com) → **ExoPhones**, select your ExoPhone and assign it an **App**. Set the passthru URL to:

    ```
    https://{PUBLIC_ASSISTANT_HOST}/v1/talk/exotel/call/{assistantId}?x-api-key={apiKey}
    ```

    Replace `{assistantId}` with the numeric assistant ID from the Rapida dashboard.
  </Step>

  <Step title="Attach vault credential to the assistant">
    In the assistant's **Phone Deployment**, select the Exotel vault credential.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    curl https://{PUBLIC_ASSISTANT_HOST}/readiness/
    # Expected: {"status":"ok"}
    ```
  </Step>
</Steps>

***

## What Rapida Returns

When Exotel hits the webhook, Rapida returns passthru XML that connects a WebSocket at:

```
wss://{PUBLIC_ASSISTANT_HOST}/v1/talk/exotel/ctx/{contextId}?x-api-key={apiKey}
```

***

## Audio Spec

| Property    | Value              |
| ----------- | ------------------ |
| Encoding    | μ-law (PCMU) 8-bit |
| Sample rate | 8000 Hz            |
| Channels    | Mono               |

***

<CardGroup>
  <Card title="Twilio" icon="phone" href="/opensource/services/assistant-api/telephony/twilio">
    Global PSTN alternative
  </Card>

  <Card title="Vonage" icon="phone" href="/opensource/services/assistant-api/telephony/vonage">
    Higher audio quality (16kHz)
  </Card>

  <Card title="Telephony Overview" icon="network" href="/opensource/services/assistant-api/telephony/overview">
    All providers and URL routing reference
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    Full env var reference
  </Card>
</CardGroup>


# Telephony — Overview
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/overview

Provider comparison, URL routing pattern, and inbound call flow for assistant-api telephony.

The `assistant-api` supports five telephony providers. Each is identified by a string constant in `api/assistant-api/internal/channel/telephony/telephony.go`.

```go theme={null}
const (
    Twilio   Telephony = "twilio"
    Exotel   Telephony = "exotel"
    Vonage   Telephony = "vonage"
    Asterisk Telephony = "asterisk"
    SIP      Telephony = "sip"
)
```

***

## Provider Comparison

| Provider                 | Transport                    | Audio Format     | Region                  |
| ------------------------ | ---------------------------- | ---------------- | ----------------------- |
| **Twilio**               | WebSocket (Media Streams)    | μ-law 8kHz       | Global                  |
| **Vonage**               | WebSocket                    | Linear PCM 16kHz | Global                  |
| **Exotel**               | WebSocket                    | μ-law 8kHz       | India / SEA             |
| **Asterisk AudioSocket** | Raw TCP port 4573            | SLIN 16-bit 8kHz | Self-hosted PBX         |
| **Asterisk WebSocket**   | WebSocket (`chan_websocket`) | μ-law 8kHz       | Self-hosted PBX         |
| **SIP**                  | UDP port 5090 + RTP          | PCM              | Direct SIP / SIP trunks |

<Info>
  **Twilio, Vonage, and Exotel** are cloud providers — they call your server. `PUBLIC_ASSISTANT_HOST` must be a publicly reachable HTTPS hostname. For local development, use [ngrok](/opensource/services/assistant-api/ngrok).

  **Asterisk** connects from your PBX to Rapida — no public URL needed on Asterisk's side.

  **SIP** is a built-in server in `assistant-api` — any SIP client dials it directly.
</Info>

***

## URL Routing

All telephony paths follow this pattern (source: `api/assistant-api/internal/type/telephony.go`):

| Path                                                           | Method     | Auth        | Purpose                                  |
| -------------------------------------------------------------- | ---------- | ----------- | ---------------------------------------- |
| `/v1/talk/{provider}/call/{assistantId}?x-api-key={apiKey}`    | POST / GET | Query param | Inbound call webhook — provider → Rapida |
| `/v1/talk/{provider}/ctx/{contextId}?x-api-key={apiKey}`       | WebSocket  | Query param | Bidirectional audio stream               |
| `/v1/talk/{provider}/ctx/{contextId}/event?x-api-key={apiKey}` | POST       | Query param | Call status / lifecycle events           |

<Info>
  All telephony endpoints authenticate via the `x-api-key` query parameter. Use a **project API key** (`rpd-xxx`) scoped to the project that owns the assistant.
</Info>

```go theme={null}
func GetContextAnswerPath(provider, contextID string) string {
    return fmt.Sprintf("v1/talk/%s/ctx/%s", provider, contextID)
}
func GetContextEventPath(provider, contextID string) string {
    return fmt.Sprintf("v1/talk/%s/ctx/%s/event", provider, contextID)
}
```

The `contextId` is generated on the first webhook hit. It is stored in PostgreSQL and binds together the call session, assistant, conversation, and auth token.

***

## Inbound Call Flow

```mermaid theme={null}
sequenceDiagram
    participant Phone as Caller (PSTN)
    participant Provider as Telephony Provider
    participant AS as assistant-api
    participant DB as PostgreSQL

    Phone->>Provider: Dials configured number
    Provider->>AS: POST /v1/talk/{provider}/call/{assistantId}
    AS->>DB: Create CallContext (contextId, assistantId, conversationId)
    AS-->>Provider: TwiML / NCCO / XML (contextId + x-api-key embedded in WebSocket URL)
    Provider->>AS: WSS /v1/talk/{provider}/ctx/{contextId}?x-api-key={apiKey}
    AS->>DB: Resolve and delete CallContext (atomic)
    AS->>AS: Start STT → LLM → TTS pipeline
    AS-->>Provider: Audio stream back to caller
```

***

## Provider Pages

<CardGroup>
  <Card title="Twilio" icon="phone" href="/opensource/services/assistant-api/telephony/twilio">
    Global PSTN via WebSocket Media Streams
  </Card>

  <Card title="Vonage" icon="phone" href="/opensource/services/assistant-api/telephony/vonage">
    Global PSTN via WebSocket NCCO
  </Card>

  <Card title="Exotel" icon="phone" href="/opensource/services/assistant-api/telephony/exotel">
    India / SEA PSTN
  </Card>

  <Card title="Asterisk" icon="server" href="/opensource/services/assistant-api/telephony/asterisk">
    Self-hosted PBX — AudioSocket and WebSocket
  </Card>

  <Card title="SIP" icon="signal" href="/opensource/services/assistant-api/telephony/sip">
    Built-in SIP server, any SIP client
  </Card>

  <Card title="Configure Your Own" icon="code" href="/opensource/services/assistant-api/telephony/custom">
    Implement the Telephony interface
  </Card>
</CardGroup>


# SIP
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/sip

Run assistant-api with the built-in SIP server for direct SIP connectivity.

The `assistant-api` includes a built-in SIP server. Any SIP client, softphone, or PBX can call it directly — no external telephony account is required.

***

## Required Configuration

```env theme={null}
# docker/assistant-api/.assistant.env
SIP__SERVER=0.0.0.0            # Bind address (listen on all interfaces)
SIP__EXTERNAL_IP=203.0.113.10  # Your server's PUBLIC IP — advertised in SDP
SIP__PORT=5090                  # SIP signalling port (UDP)
SIP__RTP_PORT_RANGE_START=10000
SIP__RTP_PORT_RANGE_END=20000
```

<Warning>
  `SIP__EXTERNAL_IP` must be your server's real public IP. If left as `0.0.0.0`, SDP will advertise a non-routable address, breaking the RTP media path — callers will hear silence.
</Warning>

***

## Firewall Ports

| Port          | Protocol | Purpose        |
| ------------- | -------- | -------------- |
| `5090`        | UDP      | SIP signalling |
| `10000–20000` | UDP      | RTP media      |

***

## Connecting a SIP Client

Route inbound calls to one of the accepted SIP destination users:

| Format                                                   | Example                                  | Resolution                                                                         |
| -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------- |
| `sip:agent-{assistantID}@{SIP__EXTERNAL_IP}:{SIP__PORT}` | `sip:agent-123456789@203.0.113.10:5090`  | Routes directly by numeric assistant ID                                            |
| `sip:did-{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}`           | `sip:did-+15551234567@203.0.113.10:5090` | Looks up the active SIP phone deployment whose phone value exactly matches `{did}` |
| `sip:{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}`               | `sip:+15551234567@203.0.113.10:5090`     | Same DID lookup, without the `did-` prefix                                         |

The DID value is matched exactly. For example, `+15551234567` and `15551234567`
are different route values.

<Warning>
  Credential-style users such as `sip:{assistantID}:{apiKey}@host` are not
  accepted for inbound routing.
</Warning>

***

## Asterisk SIP Trunk (Optional)

To route calls from Asterisk through Rapida over SIP:

<Tabs>
  <Tab title="pjsip.conf">
    ```ini theme={null}
    ; /etc/asterisk/pjsip.conf
    [rapida-trunk]
    type=endpoint
    context=rapida-outbound
    disallow=all
    allow=ulaw
    aors=rapida-trunk-aor

    [rapida-trunk-aor]
    type=aor
    contact=sip:{SIP__EXTERNAL_IP}:{SIP__PORT}

    [rapida-dialer]
    type=identify
    endpoint=rapida-trunk
    match={SIP__EXTERNAL_IP}
    ```
  </Tab>

  <Tab title="extensions.conf">
    ```ini theme={null}
    ; /etc/asterisk/extensions.conf
    [rapida-outbound]
    exten => _X.,1,NoOp(Route through Rapida SIP)
     same => n,Dial(PJSIP/did-${EXTEN}@rapida-trunk)
     same => n,Hangup()
    ```
  </Tab>
</Tabs>

***

## Rapida SaaS SIP Endpoint

For Rapida SaaS, the production SIP server is:

```
sip:agent-{assistantID}@sip-01.in.rapida.ai:5060
```

You can also route by DID:

```
sip:did-{did}@sip-01.in.rapida.ai:5060
sip:{did}@sip-01.in.rapida.ai:5060
```

***

<CardGroup>
  <Card title="Asterisk" icon="server" href="/opensource/services/assistant-api/telephony/asterisk">
    Asterisk AudioSocket and WebSocket transports
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    SIP\_\_EXTERNAL\_IP and other SIP env vars
  </Card>

  <Card title="Telephony Overview" icon="network" href="/opensource/services/assistant-api/telephony/overview">
    All providers comparison
  </Card>

  <Card title="Configure Your Own" icon="code" href="/opensource/services/assistant-api/telephony/custom">
    Add a new telephony provider
  </Card>
</CardGroup>


# Twilio
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/twilio

Run assistant-api with Twilio for global PSTN voice calls using WebSocket Media Streams.

Twilio sends a webhook when a call arrives. Rapida responds with TwiML that opens a bidirectional Media Stream (WebSocket) carrying μ-law 8kHz audio.

***

## Vault Credentials

In the Rapida dashboard go to **Credentials → Create Credential**, select provider type **Twilio**:

| Key             | Description                                               |
| --------------- | --------------------------------------------------------- |
| `account_sid`   | Twilio Account SID (`ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`) |
| `account_token` | Twilio Auth Token                                         |

***

## Setup

<Steps>
  <Step title="Set PUBLIC_ASSISTANT_HOST">
    `PUBLIC_ASSISTANT_HOST` is the public HTTPS hostname Twilio will use to reach your server — for webhooks and the WebSocket media stream.

    <Tabs>
      <Tab title="Production">
        Set it to your server's public domain in `docker/assistant-api/.assistant.env`:

        ```env theme={null}
        PUBLIC_ASSISTANT_HOST=your-server.com   # no https:// prefix
        ```

        Also update `connection.media` in `ui/src/configs/config.production.json`:

        ```json theme={null}
        {
          "connection": {
            "media": "https://your-server.com"
          }
        }
        ```
      </Tab>

      <Tab title="Local Development (ngrok)">
        Twilio's servers cannot reach `localhost`. Use ngrok to create a public HTTPS tunnel:

        **1. Install and authenticate ngrok**

        ```bash theme={null}
        # macOS
        brew install ngrok/ngrok/ngrok

        # Linux
        curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
          | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
        echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
          | sudo tee /etc/apt/sources.list.d/ngrok.list
        sudo apt update && sudo apt install ngrok

        ngrok config add-authtoken <your-authtoken>
        ```

        Get your authtoken at [dashboard.ngrok.com](https://dashboard.ngrok.com/get-started/your-authtoken).

        **2. Start the tunnel** (keep this running)

        ```bash theme={null}
        ngrok http 8080
        # Forwarding  https://abc123.ngrok-free.app -> http://localhost:8080
        ```

        **3. Update two files with the ngrok hostname**

        | File                                     | Field                   | Value                                               |
        | ---------------------------------------- | ----------------------- | --------------------------------------------------- |
        | `docker/assistant-api/.assistant.env`    | `PUBLIC_ASSISTANT_HOST` | `abc123.ngrok-free.app` *(no `https://`)*           |
        | `ui/src/configs/config.development.json` | `connection.media`      | `https://abc123.ngrok-free.app` *(with `https://`)* |

        ```env theme={null}
        # docker/assistant-api/.assistant.env
        PUBLIC_ASSISTANT_HOST=abc123.ngrok-free.app
        ```

        ```json theme={null}
        // ui/src/configs/config.development.json
        {
          "connection": {
            "media": "https://abc123.ngrok-free.app"
          }
        }
        ```

        **4. Rebuild**

        ```bash theme={null}
        make rebuild-assistant
        ```

        <Note>
          The free ngrok tier generates a new URL on every restart. When it changes, update both files above and re-run `make rebuild-assistant`. Use a [free static domain](https://ngrok.com/blog-post/free-static-domains-ngrok-users) (`ngrok http --domain=your-name.ngrok-free.app 8080`) to avoid this.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the Twilio phone number webhook">
    In [Twilio Console](https://console.twilio.com) → **Phone Numbers → Manage → Active numbers**, select your number:

    | Field                   | Value                                                                                     |
    | ----------------------- | ----------------------------------------------------------------------------------------- |
    | **A call comes in**     | Webhook, HTTP POST                                                                        |
    | **URL**                 | `https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/call/{assistantId}?x-api-key={apiKey}`    |
    | **Status callback URL** | `https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}/event?x-api-key={apiKey}` |

    Replace `{assistantId}` with the numeric assistant ID from the Rapida dashboard.
  </Step>

  <Step title="Attach vault credential to the assistant">
    In the assistant's **Phone Deployment**, select the Twilio vault credential you created.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    # Check the tunnel is proxying correctly
    curl https://{PUBLIC_ASSISTANT_HOST}/readiness/
    # Expected: {"status":"ok"}
    ```

    You can monitor Twilio webhook requests in real time at **[http://localhost:4040](http://localhost:4040)** (ngrok inspector) or in the Twilio Console under **Monitor → Logs → Calls**.
  </Step>
</Steps>

<Warning>
  `PUBLIC_ASSISTANT_HOST` must be HTTPS. Twilio rejects plain HTTP webhook URLs and `ws://` WebSocket connections — always use `https://` for the webhook URL and `wss://` for the media stream (Rapida handles this automatically).
</Warning>

***

## What Rapida Returns

When Twilio hits the inbound webhook, Rapida responds with TwiML connecting a Media Stream:

```xml theme={null}
<Response>
  <Connect>
    <Stream url="wss://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}?x-api-key={apiKey}"
            name="{assistantId}__{conversationId}"
            statusCallback="https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}/event?x-api-key={apiKey}"
            statusCallbackEvent="initiated ringing answered completed">
      <Parameter name="assistant_id" value="{assistantId}"/>
      <Parameter name="client_number" value="{callerNumber}"/>
    </Stream>
  </Connect>
</Response>
```

***

## Outbound Calls

Rapida calls `client.Api.CreateCall` via the Twilio Go SDK. The `StatusCallback`, `StatusCallbackEvent`, and `Twiml` are constructed automatically from `PUBLIC_ASSISTANT_HOST`. No additional configuration is required beyond the vault credential.

***

## Audio Spec

| Property    | Value                                           |
| ----------- | ----------------------------------------------- |
| Encoding    | μ-law (PCMU) 8-bit                              |
| Sample rate | 8000 Hz                                         |
| Channels    | Mono                                            |
| Transport   | Base64-encoded JSON frames (Media Streams spec) |

***

<CardGroup>
  <Card title="Vonage" icon="phone" href="/opensource/services/assistant-api/telephony/vonage">
    Global PSTN alternative with higher audio quality
  </Card>

  <Card title="Exotel" icon="phone" href="/opensource/services/assistant-api/telephony/exotel">
    India / SEA PSTN
  </Card>

  <Card title="Telephony Overview" icon="network" href="/opensource/services/assistant-api/telephony/overview">
    All providers and URL routing reference
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    Full env var reference
  </Card>
</CardGroup>


# Vonage
Source: https://doc.rapida.ai/opensource/services/assistant-api/telephony/vonage

Run assistant-api with Vonage (Nexmo) for global PSTN voice calls using WebSocket and NCCO.

Vonage sends a webhook when a call arrives. Rapida responds with an NCCO (Nexmo Call Control Object) that opens a WebSocket carrying Linear PCM 16kHz audio — higher quality than Twilio's μ-law.

***

## Vault Credentials

In the Rapida dashboard go to **Credentials → Create Credential**, select provider type **Vonage**:

| Key              | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| `api_key`        | Vonage API key                                                                  |
| `api_secret`     | Vonage API secret                                                               |
| `application_id` | Vonage Application ID (required for JWT auth on outbound)                       |
| `private_key`    | Vonage Application private key — PEM string (required for JWT auth on outbound) |

***

## Setup

<Steps>
  <Step title="Set PUBLIC_ASSISTANT_HOST">
    `PUBLIC_ASSISTANT_HOST` is the public HTTPS hostname Vonage will use to reach your server — for the answer URL and the WebSocket media stream.

    <Tabs>
      <Tab title="Production">
        Set it in `docker/assistant-api/.assistant.env`:

        ```env theme={null}
        PUBLIC_ASSISTANT_HOST=your-server.com   # no https:// prefix
        ```

        Also update `connection.media` in `ui/src/configs/config.production.json`:

        ```json theme={null}
        {
          "connection": {
            "media": "https://your-server.com"
          }
        }
        ```
      </Tab>

      <Tab title="Local Development (ngrok)">
        Vonage's servers cannot reach `localhost`. Use ngrok to create a public HTTPS tunnel:

        **1. Install and authenticate ngrok**

        ```bash theme={null}
        # macOS
        brew install ngrok/ngrok/ngrok

        # Linux
        curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
          | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
        echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
          | sudo tee /etc/apt/sources.list.d/ngrok.list
        sudo apt update && sudo apt install ngrok

        ngrok config add-authtoken <your-authtoken>
        ```

        Get your authtoken at [dashboard.ngrok.com](https://dashboard.ngrok.com/get-started/your-authtoken).

        **2. Start the tunnel** (keep this running)

        ```bash theme={null}
        ngrok http 8080
        # Forwarding  https://abc123.ngrok-free.app -> http://localhost:8080
        ```

        **3. Update two files with the ngrok hostname**

        | File                                     | Field                   | Value                                               |
        | ---------------------------------------- | ----------------------- | --------------------------------------------------- |
        | `docker/assistant-api/.assistant.env`    | `PUBLIC_ASSISTANT_HOST` | `abc123.ngrok-free.app` *(no `https://`)*           |
        | `ui/src/configs/config.development.json` | `connection.media`      | `https://abc123.ngrok-free.app` *(with `https://`)* |

        ```env theme={null}
        # docker/assistant-api/.assistant.env
        PUBLIC_ASSISTANT_HOST=abc123.ngrok-free.app
        ```

        ```json theme={null}
        // ui/src/configs/config.development.json
        {
          "connection": {
            "media": "https://abc123.ngrok-free.app"
          }
        }
        ```

        **4. Rebuild**

        ```bash theme={null}
        make rebuild-assistant
        ```

        <Note>
          The free ngrok tier generates a new URL on every restart. Use a [free static domain](https://ngrok.com/blog-post/free-static-domains-ngrok-users) (`ngrok http --domain=your-name.ngrok-free.app 8080`) so you only need to update Vonage's answer URL once.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a Vonage Voice Application">
    In [Vonage Dashboard](https://dashboard.nexmo.com) → **Applications → Create a new application**, enable **Voice** capability and set:

    | Field                 | Value                                                                                     |
    | --------------------- | ----------------------------------------------------------------------------------------- |
    | **Answer URL** (POST) | `https://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/call/{assistantId}?x-api-key={apiKey}`    |
    | **Event URL** (POST)  | `https://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/ctx/{contextId}/event?x-api-key={apiKey}` |

    Click **Generate public and private key** — download the private key and store the PEM content in the vault credential's `private_key` field.
  </Step>

  <Step title="Link a Vonage number">
    In **Numbers**, assign a virtual number to the application you just created.
  </Step>

  <Step title="Attach vault credential to the assistant">
    In the assistant's **Phone Deployment**, select the Vonage vault credential.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    curl https://{PUBLIC_ASSISTANT_HOST}/readiness/
    # Expected: {"status":"ok"}
    ```
  </Step>
</Steps>

***

## What Rapida Returns

When Vonage hits the answer URL, Rapida responds with an NCCO:

```json theme={null}
[{
  "action": "connect",
  "endpoint": [{
    "type": "websocket",
    "uri": "wss://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/ctx/{contextId}?x-api-key={apiKey}",
    "content-type": "audio/l16;rate=16000"
  }]
}]
```

***

## Audio Spec

| Property    | Value                       |
| ----------- | --------------------------- |
| Encoding    | Linear PCM 16-bit           |
| Sample rate | 16000 Hz                    |
| Channels    | Mono                        |
| Transport   | Raw binary WebSocket frames |

<Note>
  16kHz Linear PCM improves STT accuracy over 8kHz μ-law (Twilio/Exotel), particularly for providers that natively support 16kHz input.
</Note>

***

<CardGroup>
  <Card title="Twilio" icon="phone" href="/opensource/services/assistant-api/telephony/twilio">
    Alternative global PSTN provider
  </Card>

  <Card title="Exotel" icon="phone" href="/opensource/services/assistant-api/telephony/exotel">
    India / SEA PSTN
  </Card>

  <Card title="Telephony Overview" icon="network" href="/opensource/services/assistant-api/telephony/overview">
    All providers and URL routing reference
  </Card>

  <Card title="Configuration" icon="sliders" href="/opensource/services/assistant-api/configuration">
    Full env var reference
  </Card>
</CardGroup>


# AWS Polly TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/aws

Configure AWS Polly text-to-speech via HTTP in assistant-api.

AWS Polly provides cloud text-to-speech synthesis via Amazon Web Services. It supports neural, standard, and generative engine tiers with a broad library of voices across dozens of languages.

**Provider identifier:** `aws`

***

## Vault Credentials

| Key                 | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `access_key_id`     | AWS Access Key ID from your IAM user or role                |
| `secret_access_key` | AWS Secret Access Key corresponding to the Access Key ID    |
| `region`            | AWS region where Polly requests are sent (e.g. `us-east-1`) |

***

## Setup

<Steps>
  <Step title="Create AWS credentials with Polly access">
    In the [AWS IAM console](https://console.aws.amazon.com/iam/) → **Users → Create User** → attach the `AmazonPollyReadOnlyAccess` policy (or a scoped custom policy). Generate an access key pair under **Security credentials**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **AWS**, enter `access_key_id`, `secret_access_key`, and `region`.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **AWS Polly**.

    | Option     | Example  | Description                                                                                                       |
    | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
    | `model`    | `neural` | Engine: `neural`, `standard`, `generative`                                                                        |
    | `voice_id` | `Joanna` | Polly voice ID (e.g. `Joanna`, `Matthew`, `Amy`, `Brian`, `Ivy`, `Justin`, `Kendra`, `Kimberly`, `Salli`, `Joey`) |
    | `language` | `en-US`  | Language code: `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`, `it-IT`, `ja-JP`, `pt-BR`, and more                   |

    See the full list of voices in the [AWS Polly voice documentation](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="AWS Transcribe STT" icon="waveform" href="/opensource/services/assistant-api/stt/aws">
    AWS speech-to-text with Transcribe
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Azure TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/azure

Configure Azure Cognitive Services Neural text-to-speech in assistant-api.

Azure Cognitive Services Speech provides Neural voices across 140+ languages with SSML support.

**Provider identifier:** `azure-speech-service`

***

## Vault Credential

| Key      | Description                               |
| -------- | ----------------------------------------- |
| `key`    | Azure Speech subscription key             |
| `region` | Azure region, e.g. `eastus`, `westeurope` |

***

## Setup

<Steps>
  <Step title="Create an Azure Speech resource">
    In [Azure Portal](https://portal.azure.com) → **Create a resource → AI + Machine Learning → Speech**. Copy **Key 1** and **Region**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Azure Speech**, enter `key` = subscription key and `region` = Azure region.

    The same credential is used for both Azure STT and TTS.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Azure Speech**.

    | Option          | Example             | Description                                                                                     |
    | --------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
    | `voice_name`    | `en-US-JennyNeural` | Azure Neural voice name — see [voice gallery](https://speech.microsoft.com/portal/voicegallery) |
    | `language`      | `en-US`             | Language code                                                                                   |
    | `speaking_rate` | `1.0`               | Speed (0.5–2.0)                                                                                 |
    | `pitch`         | `0`                 | Pitch in Hz or percentage                                                                       |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Azure STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/azure">
    Azure Neural speech-to-text
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Cartesia TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/cartesia

Configure Cartesia ultra-low latency text-to-speech in assistant-api.

Cartesia is designed for real-time voice applications, offering ultra-low latency streaming synthesis optimised for conversational AI.

**Provider identifier:** `cartesia`

***

## Vault Credential

| Key   | Description                                                        |
| ----- | ------------------------------------------------------------------ |
| `key` | Cartesia API key from [play.cartesia.ai](https://play.cartesia.ai) |

***

## Setup

<Steps>
  <Step title="Get a Cartesia API key">
    Sign in at [play.cartesia.ai](https://play.cartesia.ai) → **API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Cartesia**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Cartesia**.

    | Option     | Example                                | Description                                  |
    | ---------- | -------------------------------------- | -------------------------------------------- |
    | `voice_id` | `a0e99841-438c-4a64-b679-ae501e7d6091` | Cartesia voice ID                            |
    | `model_id` | `sonic-english`                        | Model: `sonic-english`, `sonic-multilingual` |
    | `language` | `en`                                   | Language code                                |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="ElevenLabs" icon="volume" href="/opensource/services/assistant-api/tts/elevenlabs">
    High-fidelity voice cloning
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Custom TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/custom

Configure a custom WebSocket text-to-speech provider in Rapida.

Custom TTS lets you connect Rapida to any WebSocket-based speech synthesis service without writing a new Go transformer. The UI stores provider credentials and assistant options; `assistant-api` reads them through the `custom-tts` transformer and maps LLM text packets and provider audio frames with WebSocket DSL rules.

**Provider identifier:** `custom-tts`

***

## Where it is configured

<Steps>
  <Step title="Create the provider credential">
    In the Rapida dashboard, open **Integrations > Models**, choose **Custom TTS**, and create a credential.

    | Credential field   | Required | Value                                                                                       |
    | ------------------ | -------: | ------------------------------------------------------------------------------------------- |
    | `apiCompatibility` |       No | `websocket_v1`. Defaults to `websocket_v1` when omitted.                                    |
    | `baseUrl`          |      Yes | WebSocket URL for your TTS service, for example `wss://tts.example.com/v1/speak`            |
    | `headers`          |       No | Header map sent on the WebSocket handshake, for example `{"Authorization":"Bearer sk_..."}` |

    The backend also accepts snake case keys: `api_compatibility` and `base_url`.
  </Step>

  <Step title="Select Custom TTS on the assistant">
    Open the assistant voice settings and select **Custom TTS** as the text-to-speech provider.
  </Step>

  <Step title="Fill the TTS arguments">
    Set the audio format, query parameters, request rules, and response rules. The argument reference below maps to the UI fields and the transformer option keys.
  </Step>
</Steps>

***

## TTS arguments

The custom TTS transformer reads the option keys shown below. The current UI exposes the audio and DSL fields; `speak.voice.id`, `speak.model`, and `speak.language` are optional API/import metadata keys that request rules and query parameters can read when present. The UI may preserve other speaker-level settings under `speaker.*`, but the custom TTS DSL fields are unprefixed `speak.*` keys.

| Option key                | Required | Default           | Description                                                                                                                                  |
| ------------------------- | -------: | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `speak.voice.id`          |       No | Empty             | Optional provider voice identifier. Reference it in DSL as `voice_id` or `config.voice.id`.                                                  |
| `speak.model`             |       No | Empty             | Optional provider model identifier. Reference it in DSL as `model` or `config.model`.                                                        |
| `speak.language`          |       No | Empty             | Optional provider language code. Reference it in DSL as `language` or `config.language`.                                                     |
| `speak.audio.encoding`    |      Yes | `LINEAR16`        | Audio encoding expected back from the provider. Supported values: `LINEAR16`, `MuLaw8`.                                                      |
| `speak.audio.sample_rate` |      Yes | `16000`           | Audio sample rate expected back from the provider. Supported UI values are `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, and `48000`. |
| `speak.query_params`      |       No | `{}`              | Flat JSON object appended to `baseUrl` as query parameters. Values can use DSL expressions.                                                  |
| `speak.request_rules`     |      Yes | See example below | Ordered JSON array that tells Rapida what to send for each outbound packet. Must contain at least one `text` rule.                           |
| `speak.response_rules`    |      Yes | None              | Ordered JSON array that tells Rapida how to parse provider WebSocket frames into audio, done, or error events.                               |

***

## Query parameters

Use `speak.query_params` when your provider expects configuration in the WebSocket URL.

Supported variables:

| Variable      | Source                       |
| ------------- | ---------------------------- |
| `message_id`  | Current synthesis message ID |
| `voice_id`    | `speak.voice.id`             |
| `model`       | `speak.model`                |
| `language`    | `speak.language`             |
| `encoding`    | `speak.audio.encoding`       |
| `sample_rate` | `speak.audio.sample_rate`    |

```json theme={null}
{
  "voice": { "$var": "voice_id" },
  "model": { "$var": "model" },
  "language": { "$var": "language" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

<Note>
  If your provider needs a voice, model, or language and those values are not present as metadata, set them as static values inside `speak.request_rules`.
</Note>

***

## Request rules

Request rules are evaluated for normalized TTS packets produced by Rapida.

| Packet      | When it is sent                 | Available paths                                                                                                                                              |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`      | LLM text is ready for synthesis | `packet.kind`, `packet.message_id`, `packet.text`, `config.voice.id`, `config.model`, `config.language`, `config.audio.encoding`, `config.audio.sample_rate` |
| `done`      | The LLM response is complete    | `packet.kind`, `packet.message_id`, `packet.text`, `config.*`                                                                                                |
| `interrupt` | User interruption is detected   | `packet.kind`, `packet.message_id`, `packet.text`, `config.*`                                                                                                |

Supported outbound frame types are `binary`, `json`, and `text`.

<Warning>
  Add an `interrupt` rule if your provider needs an explicit cancel/clear message. Without it, queued provider audio can continue after the user starts speaking.
</Warning>

### One-shot synthesis

Use this when the provider synthesizes each text packet immediately.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "text": { "$path": "packet.text" },
        "voice_id": "narrator-1",
        "message_id": { "$path": "packet.message_id" },
        "model": "sonic-2",
        "language": "en-US",
        "audio": {
          "encoding": { "$path": "config.audio.encoding" },
          "sample_rate": {
            "$cast": "number",
            "value": { "$path": "config.audio.sample_rate" }
          }
        }
      }
    }
  }
]
```

### Two-step synthesis with done

Use this when the provider expects text first and a final flush/done packet.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "text": { "$path": "packet.text" },
        "voice_id": "narrator-1",
        "message_id": { "$path": "packet.message_id" }
      }
    }
  },
  {
    "when": { "packet": "done" },
    "send": {
      "frame": "json",
      "body": {
        "type": "done",
        "message_id": { "$path": "packet.message_id" }
      }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": {
        "type": "interrupt",
        "message_id": { "$path": "packet.message_id" }
      }
    }
  }
]
```

***

## Response rules

Response rules parse provider WebSocket frames into Rapida audio packets.

Supported inbound frame types:

| Frame    | Use when                                                               |
| -------- | ---------------------------------------------------------------------- |
| `binary` | The provider streams raw audio frames.                                 |
| `json`   | The provider returns JSON messages with base64 audio or status fields. |

Supported emit keys:

| Emit key     | Type                                 | Description                                                              |
| ------------ | ------------------------------------ | ------------------------------------------------------------------------ |
| `audio`      | Binary bytes or base64-decoded bytes | Audio chunk to play.                                                     |
| `message_id` | `string`                             | Optional message ID associated with the audio or done event.             |
| `done`       | `boolean`                            | `true` when synthesis for the message is complete.                       |
| `error`      | Any                                  | Provider error value. When present, Rapida treats the frame as an error. |

### Binary audio responses

```json theme={null}
[
  {
    "when": { "frame": "binary" },
    "emit": {
      "audio": { "$frame": "binary" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "done": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "error": { "$path": "error.message" },
      "done": true
    }
  }
]
```

### JSON base64 audio responses

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "chunk" },
    "emit": {
      "audio": {
        "$decode": "base64",
        "value": { "$path": "audio" }
      },
      "message_id": { "$path": "message_id" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "message_id" },
      "done": true
    }
  }
]
```

***

## TTS DSL design

Custom TTS uses a JSON-template DSL with three sections: query parameters, request rules, and response rules. The DSL is intentionally small. It does not run scripts, call functions, concatenate strings, perform regex matching, or read environment variables.

### TTS frame support

| Frame type | Outbound request | Inbound response | Notes                                                                            |
| ---------- | ---------------: | ---------------: | -------------------------------------------------------------------------------- |
| `binary`   |              Yes |              Yes | Use inbound binary frames for raw provider audio chunks.                         |
| `json`     |              Yes |              Yes | Use for provider request payloads, base64 audio chunks, done events, and errors. |
| `text`     |              Yes |               No | Use for outbound provider control frames when required.                          |

Inbound parsing rules:

* WebSocket message type `2` is treated as `binary`.
* Non-binary messages are parsed as JSON when they contain exactly one valid JSON value.
* Non-JSON messages are treated as `text`, but TTS response rules do not support text response frames.

### TTS operators

Every operator object must contain only that operator and its required field.

| Operator  | Where supported                                 | Description                                                                        |
| --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
| `$var`    | Query parameters                                | Reads `message_id`, `voice_id`, `model`, `language`, `encoding`, or `sample_rate`. |
| `$path`   | Request rules, response rules                   | Reads a dot path from request scope or a JSON response frame.                      |
| `$cast`   | Query parameters, request rules, response rules | Casts to `string`, `number`, or `boolean`.                                         |
| `$frame`  | Response rules                                  | Reads the full current `binary` response frame.                                    |
| `$decode` | Response rules                                  | Decodes a base64 string into bytes. Only `base64` is supported.                    |

Unsupported TTS operators:

* `$frame: "text"` and `$frame: "json"` are not supported for TTS emit rules.
* `$decode` supports only `base64`.

### Cast behavior

| Cast      | Behavior                                                                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`  | Converts strings, bytes, numbers, booleans, and null to string form.                                                                                              |
| `number`  | Converts JSON numbers, numeric values, or numeric strings to an integer or float.                                                                                 |
| `boolean` | Converts booleans, boolean strings, and numeric values. JSON numbers are accepted as `0` or `1`; typed numeric values use zero as `false` and non-zero as `true`. |

### JSON path behavior

`$path` uses dot-separated paths.

```json theme={null}
{ "$path": "packet.text" }
```

Objects are traversed by key. Arrays are traversed by numeric index.

```json theme={null}
{ "$path": "chunks.0.audio" }
```

Limits:

* Keys containing a literal dot are not addressable.
* Request rules can only read from `config` and `packet`.
* Response rules can use `$path` only with JSON response frames.
* A missing path in `when.path` means the rule does not match.
* A missing path in `emit` or `send.body` is an error.

### Query parameter rules

`speak.query_params` must be a flat JSON object. In the UI, each value must resolve to a string, number, or boolean. The backend also accepts null values and skips them when building the URL. Nested objects and arrays are rejected unless the object is a DSL expression.

```json theme={null}
{
  "voice": { "$var": "voice_id" },
  "model": { "$var": "model" },
  "sample_rate": {
    "$cast": "number",
    "value": { "$var": "sample_rate" }
  }
}
```

The rendered query parameters are appended to `baseUrl`. Existing query parameters in `baseUrl` are preserved unless the same key is rendered by `speak.query_params`.

<Note>
  TTS request rules can read `packet.text`, but `text` is not a supported query parameter variable.
</Note>

### Request rule shape

`speak.request_rules` is an ordered JSON array. Every matching rule is sent, so one packet can produce multiple WebSocket messages.

| Field         | Required | Description                          |
| ------------- | -------: | ------------------------------------ |
| `when.packet` |      Yes | `text`, `done`, or `interrupt`.      |
| `send.frame`  |      Yes | `binary`, `json`, or `text`.         |
| `send.body`   |      Yes | Static value or DSL expression tree. |

Body validation depends on `send.frame`:

| `send.frame` | `send.body` must resolve to                              |
| ------------ | -------------------------------------------------------- |
| `binary`     | Bytes or string.                                         |
| `json`       | Valid JSON value. Byte arrays are not valid JSON bodies. |
| `text`       | Value convertible to string.                             |

### TTS request scope

The request scope is the data available to `$path` in request rules.

```json theme={null}
{
  "config": {
    "voice": {
      "id": "voice_123"
    },
    "model": "model-a",
    "language": "en-US",
    "audio": {
      "encoding": "LINEAR16",
      "sample_rate": 16000
    }
  },
  "packet": {
    "kind": "text",
    "message_id": "msg_123",
    "text": "Hello world"
  }
}
```

For `done` and `interrupt`, `packet.text` is present but may be empty.

### Response rule shape

`speak.response_rules` is an ordered JSON array. The first matching rule is evaluated; later rules are skipped for that frame.

| Field         | Required | Description                                                      |
| ------------- | -------: | ---------------------------------------------------------------- |
| `when.frame`  |      Yes | `binary` or `json`.                                              |
| `when.path`   |       No | Dot path inside a JSON frame. Must be paired with `when.equals`. |
| `when.equals` |       No | Primitive value compared against `when.path`.                    |
| `emit`        |      Yes | Object containing supported TTS emit keys.                       |

Match behavior:

| Frame    | Match behavior                                                                                                                    |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `binary` | Matches by frame type only. `when.path` and `when.equals` are not allowed.                                                        |
| `json`   | If `when.path` and `when.equals` are omitted, matches any JSON frame. If provided, both fields are required and compared exactly. |

### TTS emit keys

| Emit key     | Type after evaluation | Effect                                                                                              |
| ------------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `audio`      | bytes or string       | Emits a TTS audio chunk.                                                                            |
| `message_id` | string                | Associates audio, error, or done with a message. Falls back to the current context ID when omitted. |
| `done`       | boolean               | Ends synthesis for the message, closes the connection, and emits a TTS end packet.                  |
| `error`      | string                | Emits a TTS error.                                                                                  |

### Binary audio response

Use this for providers that stream raw audio as binary WebSocket frames.

```json theme={null}
[
  {
    "when": { "frame": "binary" },
    "emit": {
      "audio": { "$frame": "binary" }
    }
  }
]
```

### JSON base64 audio response

Use `$decode` when the provider returns base64-encoded audio inside JSON.

```json theme={null}
[
  {
    "when": { "frame": "json", "path": "type", "equals": "chunk" },
    "emit": {
      "audio": {
        "$decode": "base64",
        "value": { "$path": "audio" }
      },
      "message_id": { "$path": "request_id" }
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "done" },
    "emit": {
      "message_id": { "$path": "request_id" },
      "done": true
    }
  },
  {
    "when": { "frame": "json", "path": "type", "equals": "error" },
    "emit": {
      "message_id": { "$path": "request_id" },
      "error": { "$path": "error.message" },
      "done": true
    }
  }
]
```

### Text, done, and interrupt recipe

Use this pattern when the provider expects text payloads, an explicit final message, and an explicit cancel message.

```json theme={null}
[
  {
    "when": { "packet": "text" },
    "send": {
      "frame": "json",
      "body": {
        "type": "speak",
        "text": { "$path": "packet.text" },
        "voice": { "$path": "config.voice.id" },
        "request_id": { "$path": "packet.message_id" },
        "audio": {
          "encoding": { "$path": "config.audio.encoding" },
          "sample_rate": {
            "$cast": "number",
            "value": { "$path": "config.audio.sample_rate" }
          }
        }
      }
    }
  },
  {
    "when": { "packet": "done" },
    "send": {
      "frame": "json",
      "body": {
        "type": "done",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  },
  {
    "when": { "packet": "interrupt" },
    "send": {
      "frame": "json",
      "body": {
        "type": "interrupt",
        "request_id": { "$path": "packet.message_id" }
      }
    }
  }
]
```

### Runtime behavior

* The connection URL is built from `baseUrl` and `speak.query_params`.
* Headers are copied from the credential and are not templated.
* The transformer opens a connection per active message/context. A new context closes the previous connection.
* `text` packets open the WebSocket connection if needed.
* `done` and `interrupt` request rules are optional. If no rule exists for that packet, nothing is sent.
* On interruption, Rapida sends the optional `interrupt` rule first, then closes the connection.
* Audio returned by the provider is interpreted as `speak.audio.encoding` and `speak.audio.sample_rate`, then resampled to Rapida's internal audio format when needed.
* If no response rule matches an inbound frame, the frame is ignored.
* If a response emits `error`, Rapida emits a TTS error packet.
* If a response emits `done`, Rapida closes the connection and emits a TTS end packet.

### Current TTS limits

* No regex, contains, starts-with, greater-than, or compound match conditions.
* No string interpolation or concatenation.
* No fallback values inside expressions.
* No dynamic headers or dynamic URL path segments.
* No text response handling for TTS.
* No `$frame: "json"` selector in emit rules.
* `$decode` supports only base64.

***

## Backend mapping

`assistant-api` resolves `custom-tts` in `api/assistant-api/internal/transformer/transformer.go`, then dispatches to the WebSocket v1 implementation in `api/assistant-api/internal/transformer/custom/tts_websocket_v1`.

The WebSocket v1 transformer validates:

* `baseUrl` is present in the credential.
* `speak.audio.encoding` is not empty.
* `speak.audio.sample_rate` is positive.
* `speak.request_rules` contains at least one `text` packet rule.
* `speak.response_rules` contains at least one rule.

<CardGroup>
  <Card title="Custom STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/custom">
    Configure WebSocket speech-to-text.
  </Card>

  <Card title="TTS overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    Transformer interface and supported providers.
  </Card>
</CardGroup>


# Deepgram Aura TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/deepgram

Configure Deepgram Aura text-to-speech in assistant-api.

Deepgram Aura delivers low-latency streaming synthesis over a persistent WebSocket at `wss://api.deepgram.com/v1/speak`.

**Provider identifier:** `deepgram`

***

## Vault Credential

| Key   | Description                                                                |
| ----- | -------------------------------------------------------------------------- |
| `key` | Deepgram API key from [console.deepgram.com](https://console.deepgram.com) |

***

## Setup

<Steps>
  <Step title="Get a Deepgram API key">
    Sign in at [console.deepgram.com](https://console.deepgram.com) → **API Keys → Create a new API key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Deepgram**, enter `key` = your API key.

    The same credential is used for both STT (Deepgram Nova) and TTS (Deepgram Aura).
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Deepgram**.

    | Option        | Example           | Description        |
    | ------------- | ----------------- | ------------------ |
    | `voice`       | `aura-asteria-en` | Aura voice model   |
    | `encoding`    | `linear16`        | Output encoding    |
    | `sample_rate` | `16000`           | Output sample rate |

    Available voices: `aura-asteria-en`, `aura-luna-en`, `aura-stella-en`, `aura-athena-en`, `aura-hera-en`, `aura-orion-en`, `aura-arcas-en`, `aura-perseus-en`, `aura-angus-en`, `aura-orpheus-en`, `aura-helios-en`, `aura-zeus-en`
  </Step>
</Steps>

***

## How It Works

```go theme={null}
// Initialize: connects to Deepgram Aura WebSocket
wss://api.deepgram.com/v1/speak?encoding=linear16&sample_rate=16000&model=<voice>

// Transform handles three packet types:
InterruptionPacket    → {"type":"Clear"}          // cancel queued audio
LLMResponseDeltaPacket → {"type":"Speak","text":"..."} // stream token
LLMResponseDonePacket  → {"type":"Flush"}          // trigger final synthesis
```

***

<CardGroup>
  <Card title="Deepgram STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/deepgram">
    Deepgram Nova speech-to-text
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# ElevenLabs TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/elevenlabs

Configure ElevenLabs text-to-speech with voice cloning in assistant-api.

ElevenLabs provides high-fidelity streaming speech synthesis with voice cloning capabilities. Audio is streamed via WebSocket for low-latency delivery.

**Provider identifier:** `elevenlabs`

***

## Vault Credential

| Key   | Description                                                    |
| ----- | -------------------------------------------------------------- |
| `key` | ElevenLabs API key from [elevenlabs.io](https://elevenlabs.io) |

***

## Setup

<Steps>
  <Step title="Get an ElevenLabs API key">
    Sign in at [elevenlabs.io](https://elevenlabs.io) → **Profile → API Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **ElevenLabs**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **ElevenLabs**.

    | Option             | Example                | Description                                                               |
    | ------------------ | ---------------------- | ------------------------------------------------------------------------- |
    | `voice_id`         | `21m00Tcm4TlvDq8ikWAM` | ElevenLabs voice ID                                                       |
    | `model_id`         | `eleven_turbo_v2_5`    | Model: `eleven_turbo_v2_5`, `eleven_multilingual_v2`, `eleven_flash_v2_5` |
    | `stability`        | `0.5`                  | Voice stability (0.0–1.0)                                                 |
    | `similarity_boost` | `0.75`                 | Voice clarity (0.0–1.0)                                                   |

    Find voice IDs in the [ElevenLabs Voice Library](https://elevenlabs.io/voice-library).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Cartesia" icon="zap" href="/opensource/services/assistant-api/tts/cartesia">
    Ultra-low latency alternative
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Google Cloud TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/google

Configure Google Cloud Text-to-Speech in assistant-api.

Google Cloud Text-to-Speech offers WaveNet and Neural2 voices across 100+ languages and variants.

**Provider identifier:** `google-speech-service`

***

## Vault Credential

| Key   | Description                       |
| ----- | --------------------------------- |
| `key` | Google Cloud service account JSON |

***

## Setup

<Steps>
  <Step title="Create a Google Cloud service account">
    In [Google Cloud Console](https://console.cloud.google.com) → **IAM & Admin → Service Accounts**, create a service account with the **Cloud Text-to-Speech User** role. Download the JSON key file.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Google**, paste the service account JSON as `key`.

    The same credential is used for both Google Cloud STT and TTS.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Google Speech**.

    | Option          | Example           | Description                                                                        |
    | --------------- | ----------------- | ---------------------------------------------------------------------------------- |
    | `language`      | `en-US`           | BCP-47 language code                                                               |
    | `voice_name`    | `en-US-Neural2-A` | Voice name — see [voice list](https://cloud.google.com/text-to-speech/docs/voices) |
    | `speaking_rate` | `1.0`             | Speed multiplier (0.25–4.0)                                                        |
    | `pitch`         | `0.0`             | Pitch adjustment in semitones (-20.0–20.0)                                         |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Google Cloud STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/google">
    Google Cloud speech-to-text
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Groq TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/groq

Configure Groq text-to-speech with ultra-fast HTTP inference in assistant-api.

Groq delivers text-to-speech via an OpenAI-compatible HTTP API powered by its LPU inference engine, providing extremely low-latency synthesis. It supports English and Arabic voices through the PlayAI voice collection.

**Provider identifier:** `groq`

***

## Vault Credential

| Key   | Description                                            |
| ----- | ------------------------------------------------------ |
| `key` | Groq API key from [groq.com](https://console.groq.com) |

***

## Setup

<Steps>
  <Step title="Get a Groq API key">
    Sign in at [console.groq.com](https://console.groq.com) → **API Keys → Create API Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Groq**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Groq**.

    | Option     | Example         | Description                                                                                                                                                                                                                   |
    | ---------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `model`    | `playai-tts`    | Model: `playai-tts` (English), `playai-tts-arabic` (Arabic)                                                                                                                                                                   |
    | `voice_id` | `Arista-PlayAI` | PlayAI voice name. English options include: `Arista-PlayAI`, `Atlas-PlayAI`, `Basil-PlayAI`, `Briggs-PlayAI`, `Calum-PlayAI`, `Celeste-PlayAI`, `Cheyenne-PlayAI`, `Chip-PlayAI`, `Cillian-PlayAI`, `Deedee-PlayAI`, and more |

    See the full voice list in the [Groq TTS documentation](https://console.groq.com/docs/text-speech).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Groq STT" icon="waveform" href="/opensource/services/assistant-api/stt/groq">
    Groq speech-to-text with Whisper
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# MiniMax TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/minimax

Configure MiniMax text-to-speech with HTTP streaming SSE in assistant-api.

MiniMax provides high-quality speech synthesis via HTTP streaming Server-Sent Events (SSE). It offers multiple model tiers ranging from fast turbo models to high-definition output.

**Provider identifier:** `minimax`

***

## Vault Credentials

| Key        | Description                                           |
| ---------- | ----------------------------------------------------- |
| `key`      | MiniMax API key from [minimax.io](https://minimax.io) |
| `group_id` | MiniMax Group ID associated with your account         |

***

## Setup

<Steps>
  <Step title="Get MiniMax API credentials">
    Sign in at [minimax.io](https://minimax.io) → **Account → API Keys** to retrieve your API key and Group ID.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **MiniMax**, enter `key` = your API key and `group_id` = your Group ID.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **MiniMax**.

    | Option     | Example           | Description                                                                   |
    | ---------- | ----------------- | ----------------------------------------------------------------------------- |
    | `model`    | `speech-02-turbo` | Model: `speech-02-turbo`, `speech-02-hd`, `speech-2.6-turbo`, `speech-2.6-hd` |
    | `voice_id` | `Wise_Woman`      | MiniMax voice ID (system or custom voice)                                     |

    Browse available voices in the [MiniMax TTS documentation](https://minimax.io/docs).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="ElevenLabs TTS" icon="microphone" href="/opensource/services/assistant-api/tts/elevenlabs">
    High-fidelity voice cloning alternative
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Neuphonic TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/neuphonic

Configure Neuphonic text-to-speech with WebSocket streaming in assistant-api.

Neuphonic delivers streaming speech synthesis via WebSocket with multilingual support and adjustable speech speed. Audio is streamed directly into the voice pipeline for low-latency assistant responses.

**Provider identifier:** `neuphonic`

***

## Vault Credential

| Key   | Description                                                   |
| ----- | ------------------------------------------------------------- |
| `key` | Neuphonic API key from [neuphonic.com](https://neuphonic.com) |

***

## Setup

<Steps>
  <Step title="Get a Neuphonic API key">
    Sign in at [neuphonic.com](https://neuphonic.com) → **Dashboard → API Keys** → create a new key.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Neuphonic**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Neuphonic**.

    | Option     | Example                                | Description                                                                         |
    | ---------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
    | `voice_id` | `e564ba7e-aa8d-46a2-96a8-8dffedade48f` | Neuphonic voice ID                                                                  |
    | `language` | `en`                                   | Language code: `en`, `de`, `es`, `fr`, `pt`, `it`, `nl`, `pl`, `ru`, `zh`, and more |
    | `speed`    | `1.0`                                  | Speech speed multiplier (0.1–3.0; default `1.0`)                                    |

    Browse available voices in the [Neuphonic voice library](https://neuphonic.com/voices).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Rime TTS" icon="microphone" href="/opensource/services/assistant-api/tts/rime">
    Ultra-low-latency WebSocket TTS alternative
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# NVIDIA TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/nvidia

Configure NVIDIA text-to-speech via the NVCF API in assistant-api.

NVIDIA provides text-to-speech through the NVIDIA Cloud Functions (NVCF) API, offering enterprise-grade neural voice synthesis. Voices are served from NVIDIA's inference infrastructure with high throughput.

**Provider identifier:** `nvidia`

***

## Vault Credentials

| Key           | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `key`         | NVIDIA API key from [nvidia.com](https://build.nvidia.com) |
| `function_id` | NVCF Function ID for the TTS model endpoint                |

***

## Setup

<Steps>
  <Step title="Get NVIDIA API credentials">
    Sign in at [build.nvidia.com](https://build.nvidia.com) → **API Keys** to generate your API key. Navigate to the TTS model card to find the corresponding NVCF Function ID.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **NVIDIA**, enter `key` = your API key and `function_id` = your NVCF Function ID.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **NVIDIA**.

    | Option     | Example               | Description                                                               |
    | ---------- | --------------------- | ------------------------------------------------------------------------- |
    | `voice_id` | `English-US.Female-1` | NVIDIA voice identifier (e.g. `English-US.Female-1`, `English-US.Male-1`) |
    | `language` | `en-US`               | Language code: `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`, and more      |

    Browse available voices and models in the [NVIDIA NIM catalog](https://build.nvidia.com/explore/speech).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="NVIDIA STT" icon="waveform" href="/opensource/services/assistant-api/stt/nvidia">
    NVIDIA speech recognition via NVCF
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Text-to-Speech — Overview
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/overview

TTS transformer interface, factory function, and supported providers in assistant-api.

The `assistant-api` decouples speech synthesis from provider-specific logic through the same **transformer layer** as STT. Each TTS provider implements `Transformers[LLMPacket]` and is resolved at call time by the factory.

***

## Transformer Interface

```go theme={null}
// api/assistant-api/internal/type/transformer.go
type Transformers[IN any] interface {
    Initialize() error
    Transform(ctx context.Context, in IN) error
    Close(ctx context.Context) error
}

// Type alias for TTS
type TextToSpeechTransformer = Transformers[LLMPacket]
```

### LLMPacket Types

The `LLMPacket` interface is satisfied by three packet types that TTS providers must handle:

| Packet Type              | Description                        | Action                          |
| ------------------------ | ---------------------------------- | ------------------------------- |
| `LLMResponseDeltaPacket` | A text token from the LLM stream   | Send token to TTS for synthesis |
| `LLMResponseDonePacket`  | End of LLM response                | Flush/finalise synthesis        |
| `InterruptionPacket`     | User started speaking — cancel TTS | Clear/cancel queued audio       |

```go theme={null}
// Example from Deepgram TTS:
func (d *deepgramTTS) Transform(ctx context.Context, in LLMPacket) error {
    switch pkt := in.(type) {
    case InterruptionPacket:
        return d.conn.WriteJSON(map[string]string{"type": "Clear"})
    case LLMResponseDeltaPacket:
        return d.conn.WriteJSON(map[string]string{"type": "Speak", "text": pkt.Text})
    case LLMResponseDonePacket:
        return d.conn.WriteJSON(map[string]string{"type": "Flush"})
    }
    return nil
}
```

***

## Factory Function

```go theme={null}
// api/assistant-api/internal/transformer/transformer.go
func GetTextToSpeechTransformer(
    ctx        context.Context,
    logger     commons.Logger,
    provider   string,                     // AudioTransformer constant string
    credential *protos.VaultCredential,    // decrypted vault credential
    onPacket   func(AudioPacket),          // callback invoked with each synthesised audio chunk
    opts       utils.Option,
) (TextToSpeechTransformer, error)
```

***

## Supported TTS Providers

| Provider             | Identifier              | Streaming | Notes                                                    |
| -------------------- | ----------------------- | --------- | -------------------------------------------------------- |
| **Deepgram Aura**    | `deepgram`              | ✅         | Low-latency WebSocket, `wss://api.deepgram.com/v1/speak` |
| **ElevenLabs**       | `elevenlabs`            | ✅         | High-fidelity voice cloning                              |
| **Cartesia**         | `cartesia`              | ✅         | Ultra-low latency streaming                              |
| **Google Cloud TTS** | `google-speech-service` | ✅         | WaveNet / Neural2, 100+ voices                           |
| **Azure Cognitive**  | `azure-speech-service`  | ✅         | Neural voices, 140+ languages                            |
| **Sarvam AI**        | `sarvamai`              | ✅         | Indian languages                                         |
| **Smallest AI**      | `smallest`              | ✅         | Lightning v3.1/Pro, \~100ms to first chunk               |
| **Resemble AI**      | `resemble`              | ✅         | Voice cloning                                            |
| **OpenAI TTS**       | `openai`                | ✅         | `tts-1`, `tts-1-hd`                                      |
| **AWS Polly**        | `aws`                   | ✅         | Neural voices                                            |

***

## Provider Pages

<CardGroup>
  <Card title="Deepgram Aura" icon="audio-waveform" href="/opensource/services/assistant-api/tts/deepgram">
    Low-latency WebSocket synthesis
  </Card>

  <Card title="ElevenLabs" icon="volume" href="/opensource/services/assistant-api/tts/elevenlabs">
    High-fidelity voice cloning
  </Card>

  <Card title="Cartesia" icon="zap" href="/opensource/services/assistant-api/tts/cartesia">
    Ultra-low latency
  </Card>

  <Card title="Google Cloud" icon="globe" href="/opensource/services/assistant-api/tts/google">
    WaveNet / Neural2
  </Card>

  <Card title="Azure" icon="cloud" href="/opensource/services/assistant-api/tts/azure">
    Neural voices, 140+ languages
  </Card>

  <Card title="Sarvam AI" icon="languages" href="/opensource/services/assistant-api/tts/sarvamai">
    Indian languages
  </Card>

  <Card title="Smallest AI" icon="zap" href="/opensource/services/assistant-api/tts/smallest">
    Lightning v3.1/Pro, \~100ms to first chunk
  </Card>

  <Card title="Configure Your Own" icon="code" href="/opensource/services/assistant-api/tts/custom">
    Implement the Transformers interface
  </Card>
</CardGroup>


# Resemble AI TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/resembleai

Configure Resemble AI text-to-speech with real-time WebSocket streaming in assistant-api.

Resemble AI provides high-quality, real-time neural voice synthesis and voice cloning via WebSocket streaming. Audio is streamed directly into the voice pipeline for low-latency assistant responses.

**Provider identifier:** `resembleai`

***

## Vault Credential

| Key   | Description                                                 |
| ----- | ----------------------------------------------------------- |
| `key` | Resemble AI API key from [resemble.ai](https://resemble.ai) |

***

## Setup

<Steps>
  <Step title="Get a Resemble AI API key">
    Sign in at [resemble.ai](https://app.resemble.ai) → **API** → copy your API key.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Resemble AI**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Resemble AI**.

    | Option     | Example        | Description                                                                 |
    | ---------- | -------------- | --------------------------------------------------------------------------- |
    | `voice_id` | `a1b2c3d4-...` | Voice UUID from your Resemble AI account (pre-built or custom cloned voice) |

    Browse and manage your voices in the [Resemble AI dashboard](https://app.resemble.ai).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Rime TTS" icon="microphone" href="/opensource/services/assistant-api/tts/rime">
    Ultra-low-latency WebSocket TTS alternative
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Rime TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/rime

Configure Rime text-to-speech with ultra-low-latency WebSocket streaming in assistant-api.

Rime provides ultra-low-latency streaming speech synthesis via WebSocket. Audio is streamed as PCM at 16kHz for direct pipeline integration.

**Provider identifier:** `rime`

***

## Vault Credential

| Key   | Description                                  |
| ----- | -------------------------------------------- |
| `key` | Rime API key from [rime.ai](https://rime.ai) |

***

## Setup

<Steps>
  <Step title="Get a Rime API key">
    Sign in at [rime.ai](https://rime.ai) → **Dashboard → API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Rime**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Rime**.

    | Option        | Example  | Description                                                                       |
    | ------------- | -------- | --------------------------------------------------------------------------------- |
    | `voice_id`    | `river`  | Rime voice ID (Arcana: `luna`, `celeste`, `orion`; Mist: `river`, `cove`, `peak`) |
    | `model`       | `mistv2` | Model: `mist`, `mistv2`, `arcana`                                                 |
    | `language`    | `eng`    | Language: `eng`, `spa`, `hin`, `fra`, `ger`                                       |
    | `speed_alpha` | `1.0`    | Speech speed multiplier (0.1–3.0)                                                 |

    Find available voices in the [Rime Voice Library](https://rime.ai/docs).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="ElevenLabs" icon="microphone" href="/opensource/services/assistant-api/tts/elevenlabs">
    High-fidelity voice cloning alternative
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Sarvam AI TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/sarvamai

Configure Sarvam AI text-to-speech for Indian languages in assistant-api.

Sarvam AI provides natural-sounding synthesis for Indian languages — Hindi, Bengali, Telugu, Tamil, Kannada, Malayalam, Marathi, Gujarati, Punjabi, and more.

**Provider identifier:** `sarvamai`

***

## Vault Credential

| Key   | Description                                                               |
| ----- | ------------------------------------------------------------------------- |
| `key` | Sarvam AI API key from [dashboard.sarvam.ai](https://dashboard.sarvam.ai) |

***

## Setup

<Steps>
  <Step title="Get a Sarvam AI API key">
    Sign in at [dashboard.sarvam.ai](https://dashboard.sarvam.ai) → **API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Sarvam AI**, enter `key` = your API key.

    The same credential is used for both Sarvam AI STT and TTS.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Sarvam AI**.

    | Option     | Example     | Description                                                         |
    | ---------- | ----------- | ------------------------------------------------------------------- |
    | `language` | `hi-IN`     | BCP-47 language code                                                |
    | `speaker`  | `meera`     | Voice: `meera`, `pavithra`, `maitreyi`, `arvind`, `amol`, `amartya` |
    | `model`    | `bulbul:v1` | Sarvam TTS model                                                    |
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Sarvam AI STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/sarvamai">
    Sarvam AI speech-to-text
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Smallest AI TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/smallest

Configure Smallest AI Lightning text-to-speech in assistant-api.

Smallest AI's Lightning models stream over a realtime WebSocket with \~100ms to first audio chunk. `lightning_v3.1` covers 12 languages with voice cloning; `lightning_v3.1_pro` is a premium voice pool (American, British, and Indian accents) selected per-request via the same connection.

**Provider identifier:** `smallest`

***

## Vault Credential

| Key   | Description                                                                             |
| ----- | --------------------------------------------------------------------------------------- |
| `key` | Smallest AI API key from [app.smallest.ai/dashboard](https://app.smallest.ai/dashboard) |

***

## Setup

<Steps>
  <Step title="Get a Smallest AI API key">
    Sign in at [app.smallest.ai/dashboard](https://app.smallest.ai/dashboard) → **Developer → API Keys**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Providers and Models**, add a credential, select provider **Smallest AI**, enter `key` = your API key.

    The same credential is used for both Smallest AI STT and TTS.
  </Step>

  <Step title="Configure the assistant">
    In the assistant's deployment settings → **Audio Output (TTS)**, select **Smallest AI** and pick a **Model**:

    * `lightning_v3.1` — standard pool, voice cloning supported, 12 languages
    * `lightning_v3.1_pro` — premium pool with curated American, British, and Indian accented voices (English + Hindi)

    | Option           | Example          | Description                                                                                                                       |
    | ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | `speak.model`    | `lightning_v3.1` | `lightning_v3.1` or `lightning_v3.1_pro`                                                                                          |
    | `speak.voice.id` | `magnus`         | Catalog voice, scoped to the selected model — Pro-only voices (e.g. `meher`) aren't offered under `lightning_v3.1` and vice versa |
    | `speak.language` | `en`             | Language code — Pro supports a broader set than standard                                                                          |
    | `speak.speed`    | `1.0`            | Speech speed multiplier (0.5–2.0)                                                                                                 |

    Pairing a voice with the wrong model pool is rejected by the API — the provider surfaces this as an error rather than hanging or producing garbled audio.
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Smallest AI STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/smallest">
    Smallest AI Pulse speech-to-text
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# Speechmatics TTS
Source: https://doc.rapida.ai/opensource/services/assistant-api/tts/speechmatics

Configure Speechmatics text-to-speech with HTTP streaming in assistant-api.

Speechmatics provides speech synthesis via HTTP streaming TTS, backed by the same platform known for its broad multilingual speech recognition. It supports a range of voices and languages for conversational assistant deployments.

**Provider identifier:** `speechmatics`

***

## Vault Credential

| Key   | Description                                                                   |
| ----- | ----------------------------------------------------------------------------- |
| `key` | Speechmatics API key from [speechmatics.com](https://portal.speechmatics.com) |

***

## Setup

<Steps>
  <Step title="Get a Speechmatics API key">
    Sign in at [portal.speechmatics.com](https://portal.speechmatics.com) → **API Keys → Generate API Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Speechmatics**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant">
    In the assistant settings → **TTS Provider**, select **Speechmatics**.

    | Option     | Example          | Description                                                                         |
    | ---------- | ---------------- | ----------------------------------------------------------------------------------- |
    | `voice_id` | `en-US-Neural-F` | Speechmatics voice identifier                                                       |
    | `language` | `en`             | Language code: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ja`, `zh`, and more |

    See the full voice and language list in the [Speechmatics TTS documentation](https://docs.speechmatics.com).
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Speechmatics STT" icon="waveform" href="/opensource/services/assistant-api/stt/speechmatics">
    Speechmatics real-time speech recognition
  </Card>

  <Card title="TTS Overview" icon="volume" href="/opensource/services/assistant-api/tts/overview">
    All TTS providers
  </Card>
</CardGroup>


# FireRed VAD
Source: https://doc.rapida.ai/opensource/services/assistant-api/vad/firered

Configure FireRed Voice Activity Detection in assistant-api.

[FireRed VAD](https://github.com/FireRedTeam/FireRedASR) is a DFSMN (Deep Feed-forward Sequential Memory Network) streaming model from the FireRed team at Ant Group. It uses Kaldi-compatible fbank feature extraction, CMVN normalization, and a 4-state postprocessor for precise speech boundary detection.

**Provider identifier:** `firered_vad`

***

## Source Location

```
api/assistant-api/internal/vad/internal/firered_vad/
├── firered_vad.go       # Main implementation
├── detector.go          # ONNX Runtime inference
├── fbank.go             # Kaldi-compatible fbank feature extraction
├── cmvn.go              # Cepstral mean and variance normalization
├── postprocessor.go     # 4-state speech boundary detector
├── models/
│   └── fireredvad_stream_vad_with_cache.onnx   # DFSMN model (~5 MB)
```

***

## How It Works

1. Incoming LINEAR16 bytes are converted to `int16` samples and buffered
2. Complete frames are extracted: 400 samples (25 ms) with 160-sample shift (10 ms)
3. For each frame: fbank features are extracted, CMVN normalization is applied, ONNX inference produces a raw speech probability
4. The postprocessor smooths probabilities (moving average, window size 5) and runs a 4-state machine:

```
Silence → Possible Speech → Speech → Possible Silence → Silence
```

5. Speech onset is confirmed only after the configured `start_secs` duration above the confidence threshold — this filters out short noise bursts
6. Same packet emission: `InterruptionPacket` start/end events on confirmed speech onset and offset

***

## Parameters

| Option Key                  | Default | Range | Description                                                 |
| --------------------------- | ------- | ----- | ----------------------------------------------------------- |
| `microphone.vad.confidence` | `0.7`   | 0–1   | Speech probability threshold applied after smoothing        |
| `microphone.vad.start_secs` | `0.2`   | 0–2   | Continuous speech duration before confirming speech start   |
| `microphone.vad.stop_secs`  | `0.2`   | 0–2   | Continuous non-speech duration before confirming speech end |

Internally, FireRed converts `start_secs` and `stop_secs` into its postprocessor frame counts. Each FireRed postprocessor frame represents 10 ms.

### Internal Postprocessor Defaults

These are not configurable via assistant options — they are hardcoded in `DefaultPostprocessorConfig()`:

| Setting          | Value | Description                                                                           |
| ---------------- | ----- | ------------------------------------------------------------------------------------- |
| SmoothWindowSize | 5     | Moving average window for probability smoothing                                       |
| SpeechThreshold  | 0.7   | Default smoothed probability threshold used when `microphone.vad.confidence` is unset |
| PadStartFrame    | 5     | Frames padded at speech start to capture onset audio (50 ms)                          |
| MaxSpeechFrame   | 2000  | Max consecutive speech frames before forced reset (20 seconds)                        |

***

## Model Path

| Source               | Resolution                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| Environment variable | `FIRERED_VAD_MODEL_PATH` — absolute path to the `.onnx` file                                       |
| Default (Docker)     | `./models/firered_vad/fireredvad_stream_vad_with_cache.onnx`                                       |
| Default (source)     | `api/assistant-api/internal/vad/internal/firered_vad/models/fireredvad_stream_vad_with_cache.onnx` |

***

## Local Source Setup

FireRed VAD requires ONNX Runtime (same as Silero VAD). The model file is checked into the repository.

```bash theme={null}
# Ensure ONNX Runtime is available
export CGO_CFLAGS="-I/opt/onnxruntime/include"
export CGO_LDFLAGS="-L/opt/onnxruntime/lib -lonnxruntime"
export LD_LIBRARY_PATH="/opt/onnxruntime/lib:$LD_LIBRARY_PATH"
```


# Voice Activity Detection — Overview
Source: https://doc.rapida.ai/opensource/services/assistant-api/vad/overview

VAD interface, factory function, providers, and model setup in assistant-api.

Voice Activity Detection (VAD) runs on every audio frame before STT. It determines whether the caller is speaking and emits interruption start/end signals for barge-in and turn lifecycle handling.

All three VAD providers run locally using ONNX or native C libraries. No external API calls, no credentials, no added latency.

***

## VAD Interface

Every provider implements the `Vad` interface:

```go theme={null}
// api/assistant-api/internal/type/vad.go
type Vad interface {
    Name() string
    Process(ctx context.Context, pkt UserAudioPacket) error
    Close() error
}
```

Input audio is always **16 kHz LINEAR16 mono** — the platform's internal format. Resampling from 8 kHz telephony audio happens upstream before VAD sees it.

***

## Factory Function

```go theme={null}
// api/assistant-api/internal/vad/vad.go
func GetVAD(ctx, logger, callback, options) (Vad, error)
```

The factory reads `microphone.vad.provider` from the assistant's audio options and returns the matching implementation. If no provider is set, **Silero VAD** is used as the default.

***

## Provider Identifiers

| Identifier    | Provider    | Model                                            |
| ------------- | ----------- | ------------------------------------------------ |
| `silero_vad`  | Silero VAD  | `silero_vad_20251001.onnx` (\~2 MB)              |
| `ten_vad`     | TEN VAD     | Native C library (no model file)                 |
| `firered_vad` | FireRed VAD | `fireredvad_stream_vad_with_cache.onnx` (\~5 MB) |

***

## Shared Parameters

All three providers use the same configuration keys:

| Option Key                  | Type   | Default      | Description                                                  |
| --------------------------- | ------ | ------------ | ------------------------------------------------------------ |
| `microphone.vad.provider`   | string | `silero_vad` | Provider selection                                           |
| `microphone.vad.confidence` | float  | `0.7`        | Speech probability threshold. Lower = more sensitive.        |
| `microphone.vad.start_secs` | float  | `0.2`        | Continuous speech duration before confirming speech start.   |
| `microphone.vad.stop_secs`  | float  | `0.2`        | Continuous non-speech duration before confirming speech end. |

`start_secs` and `stop_secs` are public duration values. Each provider converts them to its native VAD frame count internally.

***

## Model Files

VAD models are bundled in the Docker image at build time. For source builds, models are resolved from the source tree relative to each provider's Go package directory.

### Docker

Models are copied into the runtime image and referenced via environment variables:

```env theme={null}
SILERO_MODEL_PATH=./models/silero_vad/silero_vad_20251001.onnx
FIRERED_VAD_MODEL_PATH=./models/firered_vad/fireredvad_stream_vad_with_cache.onnx
```

TEN VAD uses a native shared library instead of an ONNX model:

```env theme={null}
LD_LIBRARY_PATH="/opt/ten_vad/lib:..."
```

These are set automatically in the Dockerfile — no manual configuration needed when running via Docker Compose.

### From Source

When running `go run cmd/assistant/assistant.go`, each provider resolves its model path using `runtime.Caller` to find the source directory:

| Provider    | Default path (relative to package dir)                                                             |
| ----------- | -------------------------------------------------------------------------------------------------- |
| Silero VAD  | `api/assistant-api/internal/vad/internal/silero_vad/models/silero_vad_20251001.onnx`               |
| FireRed VAD | `api/assistant-api/internal/vad/internal/firered_vad/models/fireredvad_stream_vad_with_cache.onnx` |
| TEN VAD     | No model file — requires `libten_vad.so` in the library path                                       |

Silero and FireRed models are checked into the repository. TEN VAD requires the shared library to be installed or available in `LD_LIBRARY_PATH` / `DYLIB_LIBRARY_PATH`.

To override model paths, set the environment variables:

```bash theme={null}
export SILERO_MODEL_PATH=/path/to/silero_vad.onnx
export FIRERED_VAD_MODEL_PATH=/path/to/fireredvad.onnx
```

***

## CGO Dependencies

All VAD providers use CGO for inference:

| Provider    | CGO dependency                  | Build flags                                                       |
| ----------- | ------------------------------- | ----------------------------------------------------------------- |
| Silero VAD  | ONNX Runtime (`libonnxruntime`) | `-I/opt/onnxruntime/include -L/opt/onnxruntime/lib -lonnxruntime` |
| FireRed VAD | ONNX Runtime (`libonnxruntime`) | Same as Silero                                                    |
| TEN VAD     | TEN VAD library (`libten_vad`)  | `-I/opt/ten_vad/include -L/opt/ten_vad/lib -lten_vad`             |

The Docker base image (`rapidaai/rapida-golang`) includes all CGO dependencies pre-installed. For local source builds, you need ONNX Runtime and the TEN VAD shared library installed on your system.

***

## Providers

| Provider                                                          | Approach                           | Best for                               |
| ----------------------------------------------------------------- | ---------------------------------- | -------------------------------------- |
| **[Silero VAD](/opensource/services/assistant-api/vad/silero)**   | ONNX model, 100+ languages         | General purpose — the default          |
| **[TEN VAD](/opensource/services/assistant-api/vad/ten)**         | Native C library, 16 ms frame hops | Lowest per-frame latency               |
| **[FireRed VAD](/opensource/services/assistant-api/vad/firered)** | DFSMN model, 4-state postprocessor | Noisy environments, precise boundaries |

See the [VAD concepts guide](/assistants/voice-activity-detection) for detailed parameter tuning guidance and use-case recommendations.


# Silero VAD
Source: https://doc.rapida.ai/opensource/services/assistant-api/vad/silero

Configure Silero Voice Activity Detection in assistant-api.

[Silero VAD](https://github.com/snakers4/silero-vad) is a pre-trained ONNX model (\~2 MB) for real-time voice activity detection. It is the default VAD provider in Rapida.

**Provider identifier:** `silero_vad`

***

## Source Location

```
api/assistant-api/internal/vad/internal/silero_vad/
├── silero_vad.go        # Main implementation
├── detector.go          # ONNX Runtime inference wrapper
├── models/
│   └── silero_vad_20251001.onnx   # Pre-trained model (~2 MB)
```

***

## How It Works

1. Incoming LINEAR16 bytes are converted to `float32` samples in the range `[-1.0, 1.0]`
2. Samples are fed to the Silero ONNX detector which produces speech segments with start/end timestamps
3. On speech onset, an `InterruptionPacket` is emitted (triggers barge-in)
4. On speech offset, an `InterruptionPacket` end event is emitted so EOS can release any pending final transcript

```go theme={null}
// Simplified flow
samples := linear16ToFloat32(pkt.Audio)
segments, _, _ := detector.Detect(samples)

if hasSpeechStart(segments) {
    callback(InterruptionPacket{...})   // barge-in
}
if hasSpeechEnd(segments) {
    callback(InterruptionPacket{...})   // end of active VAD speech
}
```

***

## Parameters

| Option Key                  | Default | Range     | Description                                                 |
| --------------------------- | ------- | --------- | ----------------------------------------------------------- |
| `microphone.vad.confidence` | `0.7`   | 0.05–0.95 | Speech probability threshold                                |
| `microphone.vad.start_secs` | `0.2`   | 0–2       | Continuous speech duration before confirming speech start   |
| `microphone.vad.stop_secs`  | `0.2`   | 0–2       | Continuous non-speech duration before confirming speech end |

Internally, `start_secs` and `stop_secs` are rounded to Silero's native frame windows: 512 samples at 16 kHz or 256 samples at 8 kHz.

***

## Model Path

| Source               | Resolution                                                                           |
| -------------------- | ------------------------------------------------------------------------------------ |
| Environment variable | `SILERO_MODEL_PATH` — absolute path to the `.onnx` file                              |
| Default (Docker)     | `./models/silero_vad/silero_vad_20251001.onnx`                                       |
| Default (source)     | `api/assistant-api/internal/vad/internal/silero_vad/models/silero_vad_20251001.onnx` |

***

## Local Source Setup

Silero VAD requires ONNX Runtime. The Docker base image includes it. For local builds:

```bash theme={null}
# macOS (Homebrew)
brew install onnxruntime

# Linux — download from https://github.com/microsoft/onnxruntime/releases
# Extract and set:
export CGO_CFLAGS="-I/opt/onnxruntime/include"
export CGO_LDFLAGS="-L/opt/onnxruntime/lib -lonnxruntime"
export LD_LIBRARY_PATH="/opt/onnxruntime/lib:$LD_LIBRARY_PATH"
```

The model file is checked into the repository — no download needed.


# TEN VAD
Source: https://doc.rapida.ai/opensource/services/assistant-api/vad/ten

Configure TEN Framework Voice Activity Detection in assistant-api.

[TEN VAD](https://github.com/TEN-framework/ten-vad) is a native C library from the TEN Framework that provides frame-level speech probability scores with a fixed 256-sample hop size (16 ms at 16 kHz).

**Provider identifier:** `ten_vad`

***

## Source Location

```
api/assistant-api/internal/vad/internal/ten_vad/
├── ten_vad.go           # Main implementation
├── detector.go          # CGO wrapper for libten_vad
├── ten_vad.h            # C header
├── lib/
│   └── Linux/x64/libten_vad.so   # Shared library
```

***

## How It Works

1. Incoming LINEAR16 bytes are converted to `int16` samples
2. Samples are processed in fixed 256-sample frames (16 ms each)
3. Each frame produces a speech probability score
4. Speech onset/offset is tracked with Pipecat-style `start_secs` and `stop_secs` debounce windows
5. Same packet emission pattern: `InterruptionPacket` start/end events on speech onset and offset

***

## Parameters

| Option Key                  | Default | Range | Description                                                 |
| --------------------------- | ------- | ----- | ----------------------------------------------------------- |
| `microphone.vad.confidence` | `0.7`   | 0–1   | Speech probability threshold                                |
| `microphone.vad.start_secs` | `0.2`   | 0–2   | Continuous speech duration before confirming speech start   |
| `microphone.vad.stop_secs`  | `0.2`   | 0–2   | Continuous non-speech duration before confirming speech end |

Internally, `start_secs` and `stop_secs` are rounded to TEN VAD's native 256-sample frames.

***

## Shared Library

TEN VAD does not use an ONNX model. It requires the `libten_vad` shared library at both build and runtime.

**Docker:** The Dockerfile copies the library from the source tree:

```dockerfile theme={null}
COPY api/assistant-api/internal/vad/internal/ten_vad/lib/Linux/x64/libten_vad.so /opt/ten_vad/lib/
```

**From source (Linux):**

```bash theme={null}
export CGO_CFLAGS="-I$(pwd)/api/assistant-api/internal/vad/internal/ten_vad"
export CGO_LDFLAGS="-L$(pwd)/api/assistant-api/internal/vad/internal/ten_vad/lib/Linux/x64 -lten_vad"
export LD_LIBRARY_PATH="$(pwd)/api/assistant-api/internal/vad/internal/ten_vad/lib/Linux/x64:$LD_LIBRARY_PATH"
```

<Warning>
  The pre-compiled shared library is for **Linux x86\_64** only. TEN VAD is not available for macOS local development. Use Silero VAD or FireRed VAD instead when developing on macOS.
</Warning>


# Document API — Configuration
Source: https://doc.rapida.ai/opensource/services/document-api/configuration

config.yaml and environment variable reference for the document-api service.

## Configuration File

The document-api uses a YAML config file at `docker/document-api/config.yaml`. Unlike the Go services, environment variables are not the primary configuration mechanism — settings are specified in YAML.

***

## Required Settings

| YAML Key                                  | Default                | Description                                                    |
| ----------------------------------------- | ---------------------- | -------------------------------------------------------------- |
| `postgres.host`                           | `postgres`             | PostgreSQL host                                                |
| `postgres.db`                             | `assistant_db`         | Database name                                                  |
| `postgres.auth.user`                      | `rapida_user`          | Database user                                                  |
| `postgres.auth.password`                  | —                      | Database password                                              |
| `elastic_search.host`                     | `opensearch`           | OpenSearch host                                                |
| `celery.broker`                           | `redis://redis:6379/0` | Celery broker URL                                              |
| `celery.backend`                          | `redis://redis:6379/0` | Celery result backend                                          |
| `authentication_config.config.secret_key` | `rpd_pks`              | JWT signing secret — must match `SECRET` in all other services |

***

## Tuning Settings

| Setting                 | Default            | Description                                                     |
| ----------------------- | ------------------ | --------------------------------------------------------------- |
| `CHUNK_SIZE`            | `1000`             | Characters per document chunk                                   |
| `CHUNK_OVERLAP`         | `100`              | Character overlap between adjacent chunks                       |
| `MAX_FILE_SIZE`         | `52428800`         | Maximum upload size in bytes (50 MB)                            |
| `EMBEDDINGS_MODEL`      | `all-MiniLM-L6-v2` | Sentence-transformers model name                                |
| `EMBEDDINGS_DIMENSION`  | `384`              | Embedding vector dimension — must match the model               |
| `CELERY_WORKERS`        | `4`                | Number of Celery worker processes                               |
| `CELERY_CONCURRENCY`    | —                  | Per-worker concurrency (reduce to lower memory usage)           |
| `EMBEDDINGS_BATCH_SIZE` | —                  | Embedding batch size (`8` = low memory, `64` = high throughput) |
| `RNNOISE_ENABLED`       | `true`             | Enable audio noise reduction                                    |
| `RNNOISE_LEVEL`         | `0.5`              | Noise reduction level (`0.0–1.0`)                               |

***

## Full Config File

```yaml theme={null}
service_name: "Document API"
host: "0.0.0.0"
port: 9010

authentication_config:
  strict: false
  type: "jwt"
  config:
    secret_key: "rpd_pks"   # Must match SECRET in other services

elastic_search:
  host: "opensearch"        # Use "localhost" for local dev
  port: 9200
  scheme: "http"
  max_connection: 5

postgres:
  host: "postgres"          # Use "localhost" for local dev
  port: 5432
  auth:
    password: "rapida_db_password"
    user: "rapida_user"
  db: "assistant_db"
  max_connection: 10
  ideal_connection: 5

internal_service:
  web_host: "web-api:9001"
  integration_host: "integration-api:9004"
  endpoint_host: "endpoint-api:9005"
  assistant_host: "assistant-api:9007"

storage:
  storage_type: "local"
  storage_path_prefix: /app/rapida-data/assets/workflow

celery:
  broker: "redis://redis:6379/0"
  backend: "redis://redis:6379/0"

knowledge_extractor_config:
  chunking_technique:
    chunker: "app.core.chunkers.statistical_chunker.StatisticalChunker"
    options:
      encoder: "app.core.encoders.openai_encoder.OpenaiEncoder"
      options:
        model_name: "text-embedding-3-large"
        api_key: "your_openai_api_key"
```

***

## Local Development Overrides

For local development, update the `host` fields in `config.yaml`:

```yaml theme={null}
elastic_search:
  host: "localhost"   # instead of "opensearch"

postgres:
  host: "localhost"   # instead of "postgres"

celery:
  broker: "redis://localhost:6379/0"
  backend: "redis://localhost:6379/0"

internal_service:
  web_host: "localhost:9001"
  integration_host: "localhost:9004"
  endpoint_host: "localhost:9005"
  assistant_host: "localhost:9007"
```

***

## Next Steps

<CardGroup>
  <Card title="Overview" icon="server" href="/opensource/services/document-api/overview">
    Document processing pipeline, file formats, and RAG search.
  </Card>

  <Card title="Configuration Reference" icon="sliders" href="/opensource/configuration">
    Cross-service configuration reference.
  </Card>
</CardGroup>


# Document API
Source: https://doc.rapida.ai/opensource/services/document-api/overview

Knowledge base and RAG pipeline. Handles document ingestion, chunking, embedding generation, and semantic search for assistant context retrieval.

## Purpose

<Warning>
  **This service is optional.** `document-api` and `opensearch` are only needed for knowledge base / RAG features. Voice assistants (STT/LLM/TTS) work fully without them. Use `make up-all-with-knowledge` to start with knowledge base support.
</Warning>

The `document-api` is the knowledge backend for the Rapida platform. It ingests documents (PDF, Word, CSV, and others), splits them into chunks, generates vector embeddings, and indexes everything in OpenSearch. At call time, `assistant-api` queries this service to inject relevant context into the LLM prompt.

<CardGroup>
  <Card title="Port" icon="server">
    `9010` — HTTP (FastAPI / uvicorn)
  </Card>

  <Card title="Language" icon="code">
    Python 3.11+
    FastAPI + Celery
  </Card>

  <Card title="Storage" icon="database">
    PostgreSQL `assistant_db`
    Redis (Celery broker)
    OpenSearch (vectors + text)
  </Card>
</CardGroup>

<Info>
  Document processing is asynchronous. Upload returns immediately with `status: processing`. Text extraction, chunking, and embedding generation run as Celery background tasks.
</Info>

***

## Document Processing Pipeline

```mermaid theme={null}
sequenceDiagram
    participant UI as Dashboard (UI)
    participant Doc as document-api :9010
    participant PG as PostgreSQL (assistant_db)
    participant Redis as Redis (Celery)
    participant OS as OpenSearch

    UI->>Doc: POST /api/v1/document/upload (file)
    Doc->>PG: Create document record (status: pending)
    Doc->>Redis: Enqueue process_document task
    Doc-->>UI: { document_id, status: "processing" }

    Redis->>Doc: Worker picks up task
    Doc->>Doc: 1 — Extract text (format-specific handler)
    Doc->>Doc: 2 — Split into chunks (CHUNK_SIZE + CHUNK_OVERLAP)
    Doc->>Doc: 3 — Generate embeddings (sentence-transformers)
    Doc->>PG: Store chunks + embedding vectors
    Doc->>OS: Index chunks for full-text + vector search
    Doc->>PG: Update status: "completed"
```

***

## Supported File Formats

| Format            | Library            | What is Extracted          |
| ----------------- | ------------------ | -------------------------- |
| PDF               | PyPDF2, pdfplumber | Text content + metadata    |
| Word (.docx)      | python-docx        | Text + paragraph structure |
| Excel (.xlsx)     | openpyxl, pandas   | Cell values as text        |
| CSV               | pandas             | Row data as text           |
| Markdown (.md)    | built-in           | Text preserving structure  |
| HTML              | BeautifulSoup      | Cleaned text from HTML     |
| Plain text (.txt) | built-in           | Direct read                |
| Images            | pytesseract (OCR)  | OCR-extracted text         |

***

## Semantic Search

At call time, `assistant-api` sends a text query to `document-api`. The service performs vector similarity search and returns the top-k most relevant chunks.

**Request:**

```bash theme={null}
curl -X POST http://localhost:9010/api/v1/document/search \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "customer billing issue",
    "knowledge_base_id": "kb_123",
    "top_k": 5,
    "threshold": 0.5
  }'
```

**Response:**

```json theme={null}
{
  "results": [
    {
      "chunk_id": "chunk_123",
      "document_id": "doc_456",
      "content": "Billing errors are handled by submitting a refund request...",
      "similarity_score": 0.87,
      "metadata": {
        "page_no": 5,
        "section": "Billing Policy"
      }
    }
  ]
}
```

***

## Embedding Models

Embeddings are generated using [sentence-transformers](https://www.sbert.net/). The model is configurable via `EMBEDDINGS_MODEL` in `config.yaml`:

| Model                  | Dimensions | Notes                       |
| ---------------------- | ---------- | --------------------------- |
| `all-MiniLM-L6-v2`     | 384        | **Default** — \~80 MB, fast |
| `all-mpnet-base-v2`    | 768        | Higher quality, larger      |
| `all-MiniLM-L12-v2`    | 384        | Lighter variant of L6       |
| `multilingual-e5-base` | 768        | 100+ languages              |

<Note>
  If you change `EMBEDDINGS_MODEL`, you must also update `EMBEDDINGS_DIMENSION` to match and re-index all existing documents. Existing embeddings stored with a different dimension will not match.
</Note>

***

## Running

<Tabs>
  <Tab title="Docker Compose">
    `document-api` is part of the `knowledge` Docker Compose profile and is not started by default.

    ```bash theme={null}
    # Start document-api together with all other services and opensearch
    make up-all-with-knowledge

    # Or start document-api individually (opensearch must already be running)
    make up-document

    # View logs
    make logs-document

    # Rebuild
    make rebuild-document
    ```
  </Tab>

  <Tab title="From Source">
    Requires Python 3.11+, PostgreSQL 15, Redis 7, and OpenSearch 2.11 running locally. All commands run from the **repository root**.

    ```bash theme={null}
    # 1. Create and activate virtual environment
    cd api/document-api
    python3 -m venv venv
    source venv/bin/activate   # Windows: venv\Scripts\activate

    # 2. Install dependencies
    pip install -r requirements.txt

    # 3. Return to repository root
    cd ../..

    # 4. Start the API server
    PYTHONPATH=api/document-api uvicorn app.main:app --host 0.0.0.0 --port 9010

    # 5. In a separate terminal — start the Celery worker
    cd api/document-api && source venv/bin/activate && cd ../..
    PYTHONPATH=api/document-api celery -A app.worker worker --loglevel=info
    ```

    <Warning>
      All commands must be run from the **repository root** with `PYTHONPATH=api/document-api` set. Running `uvicorn` directly from inside `api/document-api/` will cause import errors.
    </Warning>
  </Tab>
</Tabs>

***

## Health Endpoints

| Endpoint          | Purpose        |
| ----------------- | -------------- |
| `GET /readiness/` | Service ready  |
| `GET /healthz/`   | Liveness probe |

```bash theme={null}
curl http://localhost:9010/readiness/
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Document stuck in 'processing' status">
    The Celery worker is likely not running.

    ```bash theme={null}
    # Docker
    make logs-document

    # Local — confirm Celery worker is running
    PYTHONPATH=api/document-api celery -A app.worker inspect active
    ```
  </Accordion>

  <Accordion title="Embedding generation is slow">
    Adjust the Celery worker batch size:

    ```
    EMBEDDINGS_BATCH_SIZE=8     # Low memory
    EMBEDDINGS_BATCH_SIZE=64    # High throughput (GPU recommended)
    ```
  </Accordion>

  <Accordion title="OpenSearch index errors">
    ```bash theme={null}
    # List existing indices
    curl http://localhost:9200/_cat/indices

    # Delete a stale index and allow re-indexing
    curl -X DELETE http://localhost:9200/documents-<index-name>
    ```
  </Accordion>

  <Accordion title="High memory usage">
    ```
    CELERY_CONCURRENCY=2
    ```

    ```bash theme={null}
    docker stats document-api
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/opensource/services/document-api/configuration">
    config.yaml reference — chunking, embedding, Celery, and storage settings.
  </Card>

  <Card title="Assistant API" icon="mic" href="/opensource/services/assistant-api/overview">
    How assistants query knowledge bases during calls.
  </Card>

  <Card title="Architecture" icon="network" href="/opensource/architecture">
    Full system topology and RAG data flow.
  </Card>

  <Card title="Overview" icon="rocket" href="/opensource/overview">
    Deploy the full platform with Docker Compose.
  </Card>
</CardGroup>


# Endpoint API — Configuration
Source: https://doc.rapida.ai/opensource/services/endpoint-api/configuration

Complete environment variable reference for the endpoint-api service.

## Configuration File

Edit `docker/endpoint-api/.endpoint.env` before starting the service.

***

## Required Variables

| Variable                   | Default       | Description                                                |
| -------------------------- | ------------- | ---------------------------------------------------------- |
| `SECRET`                   | `rpd_pks`     | JWT signing secret — must be identical across all services |
| `POSTGRES__HOST`           | `postgres`    | PostgreSQL host                                            |
| `POSTGRES__DB_NAME`        | `endpoint_db` | Database name                                              |
| `POSTGRES__AUTH__USER`     | `rapida_user` | Database user                                              |
| `POSTGRES__AUTH__PASSWORD` | —             | Database password                                          |
| `REDIS__HOST`              | `redis`       | Redis host (job queue for retries)                         |

***

## Service Identity

| Variable       | Default        | Description                              |
| -------------- | -------------- | ---------------------------------------- |
| `SERVICE_NAME` | `endpoint-api` | Internal service label                   |
| `HOST`         | `0.0.0.0`      | Bind address                             |
| `PORT`         | `9005`         | HTTP / gRPC port                         |
| `LOG_LEVEL`    | `debug`        | `debug` · `info` · `warn` · `error`      |
| `ENV`          | `development`  | `development` · `staging` · `production` |

***

## PostgreSQL

| Variable                         | Default              | Description                           |
| -------------------------------- | -------------------- | ------------------------------------- |
| `POSTGRES__HOST`                 | `postgres`           | Host (`localhost` for local dev)      |
| `POSTGRES__PORT`                 | `5432`               | Port                                  |
| `POSTGRES__DB_NAME`              | `endpoint_db`        | Database name                         |
| `POSTGRES__AUTH__USER`           | `rapida_user`        | User                                  |
| `POSTGRES__AUTH__PASSWORD`       | `rapida_db_password` | Password                              |
| `POSTGRES__MAX_OPEN_CONNECTION`  | `15`                 | Connection pool size                  |
| `POSTGRES__MAX_IDEAL_CONNECTION` | `8`                  | Idle connections                      |
| `POSTGRES__SSL_MODE`             | `disable`            | `disable` · `require` · `verify-full` |

***

## Redis

| Variable                | Default | Description                            |
| ----------------------- | ------- | -------------------------------------- |
| `REDIS__HOST`           | `redis` | Redis host (`localhost` for local dev) |
| `REDIS__PORT`           | `6379`  | Redis port                             |
| `REDIS__DB`             | `2`     | Redis DB index                         |
| `REDIS__MAX_CONNECTION` | `10`    | Connection pool size                   |

***

## Webhook Delivery Settings

| Variable              | Default | Description                           |
| --------------------- | ------- | ------------------------------------- |
| `WEBHOOK_MAX_RETRIES` | `5`     | Maximum delivery attempts per event   |
| `WEBHOOK_RETRY_DELAY` | `5000`  | Initial retry delay in milliseconds   |
| `WEBHOOK_TIMEOUT`     | `30000` | HTTP delivery timeout in milliseconds |

***

## Full Environment File

```env theme={null}
# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=endpoint-api
HOST=0.0.0.0
PORT=9005
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__PORT=5432
POSTGRES__DB_NAME=endpoint_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__MAX_OPEN_CONNECTION=15
POSTGRES__MAX_IDEAL_CONNECTION=8
POSTGRES__SSL_MODE=disable

# ── Redis (retry job queue) ───────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__DB=2
REDIS__MAX_CONNECTION=10

# ── Webhook delivery settings ─────────────────────────────────────
WEBHOOK_MAX_RETRIES=5
WEBHOOK_RETRY_DELAY=5000
WEBHOOK_TIMEOUT=30000
```

***

## Next Steps

<CardGroup>
  <Card title="Overview" icon="server" href="/opensource/services/endpoint-api/overview">
    Endpoint API purpose, event routing, and retry strategy.
  </Card>

  <Card title="Configuration Reference" icon="sliders" href="/opensource/configuration">
    Cross-service configuration reference.
  </Card>
</CardGroup>


# Endpoint API
Source: https://doc.rapida.ai/opensource/services/endpoint-api/overview

Webhook and callback management. Routes post-call events to external systems with configurable retry, signature verification, and delivery history.

## Purpose

The `endpoint-api` delivers conversation events to external HTTP endpoints. When a call starts, ends, or a message is exchanged, `assistant-api` emits events to `endpoint-api` via gRPC. This service handles fan-out to all registered webhooks, retry with exponential backoff, HMAC-SHA256 payload signing, and delivery tracking.

<CardGroup>
  <Card title="Port" icon="server">
    `9005` — HTTP · gRPC (cmux)
  </Card>

  <Card title="Language" icon="code">
    Go 1.25
    Gin (REST) + gRPC
  </Card>

  <Card title="Storage" icon="database">
    PostgreSQL `endpoint_db`
    Redis (retry job queue)
  </Card>
</CardGroup>

***

## Event Delivery Flow

```mermaid theme={null}
sequenceDiagram
    participant AS as assistant-api
    participant EP as endpoint-api :9005
    participant Redis as Redis (retry queue)
    participant WH as External Webhook

    AS->>EP: gRPC EmitEvent(conversation.ended, payload)
    EP->>EP: Resolve active webhooks for project
    EP->>EP: Sign payload with HMAC-SHA256
    EP->>WH: POST webhook URL with X-Rapida-Signature header
    alt 2xx response
        WH-->>EP: 200 OK
        EP->>EP: Mark delivery success
    else 408 / 429 / 5xx
        WH-->>EP: 503 Service Unavailable
        EP->>Redis: Enqueue retry with exponential backoff
        Redis->>EP: Worker retries after delay
    end
```

***

## Core Components

<AccordionGroup>
  <Accordion title="Webhook Registry">
    Each webhook is scoped to a project and subscribes to one or more event types.

    | Field         | Type      | Description                            |
    | ------------- | --------- | -------------------------------------- |
    | `name`        | string    | Human-readable label                   |
    | `url`         | string    | Destination HTTPS endpoint             |
    | `events`      | string\[] | Subscribed event types                 |
    | `is_active`   | bool      | Enable / disable without deleting      |
    | `secret`      | string    | HMAC signing secret                    |
    | `max_retries` | int       | Default: `5`                           |
    | `timeout_ms`  | int       | Default: `30000`                       |
    | `headers`     | JSON      | Custom headers sent with each delivery |
  </Accordion>

  <Accordion title="Retry Strategy">
    | Attempt | Delay      |
    | ------- | ---------- |
    | 1       | Immediate  |
    | 2       | 5 seconds  |
    | 3       | 25 seconds |
    | 4       | 2 minutes  |
    | 5       | 10 minutes |

    Retries trigger on HTTP `408`, `429`, and `5xx`. Status `2xx` = success. Status `4xx` (except `408`, `429`) = non-retriable failure.
  </Accordion>

  <Accordion title="Payload Signing">
    Every delivery includes an `X-Rapida-Signature` header:

    ```
    X-Rapida-Signature: sha256=<hmac-sha256-hex>
    ```

    **Verification (Node.js):**

    ```javascript theme={null}
    const crypto = require('crypto');

    function verifySignature(rawBody, signatureHeader, secret) {
      const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(rawBody)
        .digest('hex');
      return crypto.timingSafeEqual(
        Buffer.from(signatureHeader),
        Buffer.from(expected)
      );
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Event Reference

| Event                  | Trigger           | Key Payload Fields                                               |
| ---------------------- | ----------------- | ---------------------------------------------------------------- |
| `conversation.started` | Call begins       | `conversation_id`, `assistant_id`, `timestamp`                   |
| `conversation.ended`   | Call terminates   | `conversation_id`, `duration_ms`, `messages_count`, `end_reason` |
| `message.sent`         | Assistant speaks  | `conversation_id`, `message_id`, `content`, `role`               |
| `message.received`     | User speaks       | `conversation_id`, `message_id`, `content`, `role`               |
| `assistant.updated`    | Config changed    | `assistant_id`, `changes`                                        |
| `assistant.deleted`    | Assistant removed | `assistant_id`, `timestamp`                                      |
| `error.occurred`       | Pipeline error    | `conversation_id`, `error_code`, `error_message`                 |

**Example payload — `conversation.ended`:**

```json theme={null}
{
  "id": "evt_1234567890abcdef",
  "type": "conversation.ended",
  "timestamp": 1704067200000,
  "data": {
    "conversation_id": "conv_abc123",
    "assistant_id": "asst_def456",
    "duration_ms": 125000,
    "messages_count": 8,
    "end_reason": "user_hangup"
  }
}
```

***

## API Endpoints

| Method   | Path                                        | Description             |
| -------- | ------------------------------------------- | ----------------------- |
| `GET`    | `/readiness/`                               | Readiness probe         |
| `GET`    | `/healthz/`                                 | Liveness probe          |
| `POST`   | `/api/v1/endpoint/webhooks`                 | Create webhook          |
| `GET`    | `/api/v1/endpoint/webhooks`                 | List webhooks           |
| `GET`    | `/api/v1/endpoint/webhooks/{id}`            | Get webhook             |
| `PUT`    | `/api/v1/endpoint/webhooks/{id}`            | Update webhook          |
| `DELETE` | `/api/v1/endpoint/webhooks/{id}`            | Delete webhook          |
| `POST`   | `/api/v1/endpoint/webhooks/{id}/test`       | Send test event         |
| `GET`    | `/api/v1/endpoint/webhooks/{id}/deliveries` | List delivery history   |
| `POST`   | `/api/v1/endpoint/webhooks/{id}/replay`     | Replay a specific event |

**Create a webhook:**

```bash theme={null}
curl -X POST http://localhost:9005/api/v1/endpoint/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Sync",
    "url": "https://crm.example.com/webhooks/rapida",
    "events": ["conversation.ended", "message.sent"],
    "headers": {"Authorization": "Bearer crm-api-key"},
    "max_retries": 5,
    "timeout_ms": 30000
  }'
```

**Replay a failed event:**

```bash theme={null}
curl -X POST http://localhost:9005/api/v1/endpoint/webhooks/{id}/replay \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "evt_1234567890abcdef"}'
```

***

## Running

<Tabs>
  <Tab title="Docker Compose">
    ```bash theme={null}
    make up-endpoint

    make logs-endpoint

    make rebuild-endpoint
    ```
  </Tab>

  <Tab title="From Source">
    Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.

    ```bash theme={null}
    export $(grep -v '^#' docker/endpoint-api/.endpoint.env | xargs)
    export POSTGRES__HOST=localhost
    export REDIS__HOST=localhost

    go run cmd/endpoint/endpoint.go
    ```
  </Tab>
</Tabs>

***

## Health Endpoints

| Endpoint          | Purpose                              |
| ----------------- | ------------------------------------ |
| `GET /readiness/` | Service ready (DB + Redis connected) |
| `GET /healthz/`   | Liveness probe                       |

```bash theme={null}
curl http://localhost:9005/readiness/
```

***

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/opensource/services/endpoint-api/configuration">
    Environment variables including webhook retry settings.
  </Card>

  <Card title="Assistant API" icon="mic" href="/opensource/services/assistant-api/overview">
    Event emitter — assistant-api fires conversation events to endpoint-api.
  </Card>

  <Card title="Architecture" icon="network" href="/opensource/architecture">
    Full system topology and data flows.
  </Card>

  <Card title="Integration API" icon="plug" href="/opensource/services/integration-api/overview">
    LLM provider execution layer.
  </Card>
</CardGroup>


# Integration API — Configuration
Source: https://doc.rapida.ai/opensource/services/integration-api/configuration

Complete environment variable reference for the integration-api service.

## Configuration File

Edit `docker/integration-api/.integration.env` before starting the service.

***

## Required Variables

| Variable                   | Default          | Description                                                |
| -------------------------- | ---------------- | ---------------------------------------------------------- |
| `SECRET`                   | `rpd_pks`        | JWT signing secret — must be identical across all services |
| `POSTGRES__HOST`           | `postgres`       | PostgreSQL host                                            |
| `POSTGRES__DB_NAME`        | `integration_db` | Database name                                              |
| `POSTGRES__AUTH__USER`     | `rapida_user`    | Database user                                              |
| `POSTGRES__AUTH__PASSWORD` | —                | Database password                                          |
| `REDIS__HOST`              | `redis`          | Redis host                                                 |
| `INTEGRATION_CRYPTO_KEY`   | —                | **AES-256-GCM encryption key** for provider credentials    |
| `WEB_HOST`                 | `web-api:9001`   | web-api gRPC address                                       |

<Warning>
  `INTEGRATION_CRYPTO_KEY` protects all stored provider credentials. If this key is rotated or lost, all stored credentials become unreadable and must be re-entered through the dashboard. Store it in a secret manager (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) — never commit it to version control.

  Generate a key: `openssl rand -hex 32`
</Warning>

***

## Service Identity

| Variable       | Default           | Description                              |
| -------------- | ----------------- | ---------------------------------------- |
| `SERVICE_NAME` | `integration-api` | Internal service label                   |
| `HOST`         | `0.0.0.0`         | Bind address                             |
| `PORT`         | `9004`            | HTTP / gRPC port                         |
| `LOG_LEVEL`    | `debug`           | `debug` · `info` · `warn` · `error`      |
| `ENV`          | `development`     | `development` · `staging` · `production` |

***

## PostgreSQL

| Variable                        | Default              | Description                           |
| ------------------------------- | -------------------- | ------------------------------------- |
| `POSTGRES__HOST`                | `postgres`           | Host (`localhost` for local dev)      |
| `POSTGRES__PORT`                | `5432`               | Port                                  |
| `POSTGRES__DB_NAME`             | `integration_db`     | Database name                         |
| `POSTGRES__AUTH__USER`          | `rapida_user`        | User                                  |
| `POSTGRES__AUTH__PASSWORD`      | `rapida_db_password` | Password                              |
| `POSTGRES__MAX_OPEN_CONNECTION` | `10`                 | Connection pool size                  |
| `POSTGRES__SSL_MODE`            | `disable`            | `disable` · `require` · `verify-full` |

***

## Redis

| Variable      | Default | Description                            |
| ------------- | ------- | -------------------------------------- |
| `REDIS__HOST` | `redis` | Redis host (`localhost` for local dev) |
| `REDIS__PORT` | `6379`  | Redis port                             |

***

## Optional OAuth Variables

Used when provider OAuth flows are enabled (Google, GitHub):

| Variable                     | Description                    |
| ---------------------------- | ------------------------------ |
| `OAUTH_CALLBACK_URL`         | OAuth redirect URI             |
| `GOOGLE_OAUTH_CLIENT_ID`     | Google OAuth app client ID     |
| `GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth app client secret |
| `GITHUB_OAUTH_CLIENT_ID`     | GitHub OAuth app client ID     |
| `GITHUB_OAUTH_CLIENT_SECRET` | GitHub OAuth app client secret |

***

## Full Environment File

```env theme={null}
# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=integration-api
HOST=0.0.0.0
PORT=9004
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__PORT=5432
POSTGRES__DB_NAME=integration_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__MAX_OPEN_CONNECTION=10
POSTGRES__SSL_MODE=disable

# ── Redis ─────────────────────────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379

# ── Credential encryption ─────────────────────────────────────────
# Generate: openssl rand -hex 32
INTEGRATION_CRYPTO_KEY=your_32_char_encryption_key_here

# ── Internal service addresses ────────────────────────────────────
WEB_HOST=web-api:9001
```

***

## Next Steps

<CardGroup>
  <Card title="Adding Providers" icon="plug" href="/opensource/services/integration-api/providers">
    How to implement the LargeLanguageCaller interface.
  </Card>

  <Card title="Overview" icon="server" href="/opensource/services/integration-api/overview">
    Integration API purpose and credential encryption.
  </Card>
</CardGroup>


# Anthropic
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/anthropic

Configure Anthropic Claude models in integration-api.

The Anthropic caller uses the Anthropic Go SDK with streaming via `onStream` callbacks. Note that Claude requires `max_tokens` to be set explicitly.

**Provider directory:** `api/integration-api/internal/caller/anthropic/`

***

## Vault Credential

| Key   | Description                                                                   |
| ----- | ----------------------------------------------------------------------------- |
| `key` | Anthropic API key from [console.anthropic.com](https://console.anthropic.com) |

***

## Setup

<Steps>
  <Step title="Get an Anthropic API key">
    Sign in at [console.anthropic.com](https://console.anthropic.com) → **API Keys → Create Key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Anthropic**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant LLM">
    In the assistant settings → **LLM Provider**, select **Anthropic** and set model parameters:

    ```json theme={null}
    {
      "model.name": "claude-sonnet-4-6",
      "model.max_tokens": 1024,
      "model.temperature": 0.7
    }
    ```

    <Warning>
      `model.max_tokens` is **required** for Anthropic. The API will return an error if it is not set.
    </Warning>
  </Step>
</Steps>

***

## Supported Models

| Model                       | Context | Notes                                       |
| --------------------------- | ------- | ------------------------------------------- |
| `claude-opus-4-6`           | 200k    | Most capable                                |
| `claude-sonnet-4-6`         | 200k    | Best speed/capability balance (recommended) |
| `claude-haiku-4-5-20251001` | 200k    | Fastest, lowest cost                        |

***

## Model Parameters

| Key                 | Supported | Notes                     |
| ------------------- | --------- | ------------------------- |
| `model.name`        | ✅         | Required                  |
| `model.max_tokens`  | ✅         | **Required** — no default |
| `model.temperature` | ✅         | 0.0–1.0                   |
| `model.top_p`       | ✅         |                           |
| `model.top_k`       | ✅         | Anthropic-specific        |
| `model.stop`        | ✅         | Array of stop sequences   |
| `model.thinking`    | ✅         | Extended thinking mode    |

***

<CardGroup>
  <Card title="OpenAI" icon="sparkles" href="/opensource/services/integration-api/llm/openai">
    GPT-4o models
  </Card>

  <Card title="LLM Overview" icon="network" href="/opensource/services/integration-api/llm/overview">
    All providers and ChatCompletionOptions
  </Card>
</CardGroup>


# Azure OpenAI
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/azure

Configure Azure-hosted OpenAI deployments in integration-api.

The Azure caller uses the same OpenAI API surface but targets your Azure OpenAI resource endpoint. This is useful when data residency or enterprise compliance requirements prevent using OpenAI directly.

**Provider directory:** `api/integration-api/internal/caller/azure/`

***

## Vault Credential

| Key                | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `subscription_key` | Azure OpenAI resource key (Key 1 or Key 2)                                  |
| `endpoint`         | Azure OpenAI resource endpoint, e.g. `https://my-resource.openai.azure.com` |

***

## Setup

<Steps>
  <Step title="Create an Azure OpenAI resource">
    In [Azure Portal](https://portal.azure.com) → **Create a resource → Azure OpenAI**. After creation, go to **Keys and Endpoint** to copy the key and endpoint.
  </Step>

  <Step title="Deploy a model">
    In [Azure OpenAI Studio](https://oai.azure.com) → **Deployments → Create new deployment**. Select a model (e.g. `gpt-4o`) and give it a deployment name.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Azure OpenAI**, enter:

    * `subscription_key` = Key 1 from Azure
    * `endpoint` = resource endpoint URL
  </Step>

  <Step title="Configure the assistant LLM">
    In the assistant settings → **LLM Provider**, select **Azure OpenAI** and set the deployment name as the model:

    ```json theme={null}
    {
      "model.name": "my-gpt4o-deployment",
      "model.temperature": 0.7,
      "model.max_tokens": 200
    }
    ```

    `model.name` must match your Azure deployment name exactly.
  </Step>
</Steps>

***

## Model Parameters

Same as OpenAI — all `model.*` parameters are supported. See the [OpenAI page](/opensource/services/integration-api/llm/openai) for the full table.

***

<CardGroup>
  <Card title="OpenAI" icon="sparkles" href="/opensource/services/integration-api/llm/openai">
    Direct OpenAI API
  </Card>

  <Card title="LLM Overview" icon="network" href="/opensource/services/integration-api/llm/overview">
    All providers and ChatCompletionOptions
  </Card>
</CardGroup>


# Custom LLM
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/custom

Configure a custom LLM endpoint through integration-api.

Custom LLM lets you connect Rapida to a self-hosted or third-party chat endpoint. The UI stores provider credentials and model options; `integration-api` resolves the `custom-llm` provider and routes requests through the selected API compatibility.

**Provider identifier:** `custom-llm`

***

## Where it is configured

<Steps>
  <Step title="Create the provider credential">
    In the Rapida dashboard, open **Integrations > Models**, choose **Custom LLM**, and create a credential.

    | Credential field   | Required | Value                                                                                |
    | ------------------ | -------: | ------------------------------------------------------------------------------------ |
    | `apiCompatibility` |      Yes | API shape to call. See compatibility values below.                                   |
    | `baseUrl`          |      Yes | Base URL for the model server.                                                       |
    | `headers`          |       No | Header map sent with every request, for example `{"Authorization":"Bearer sk_..."}`. |

    The backend also accepts snake case keys: `api_compatibility` and `base_url`.
  </Step>

  <Step title="Choose the custom model in the assistant">
    Open the assistant model settings, choose **Custom LLM**, and enter the model ID. The UI stores both `model.id` and `model.name` for custom model values.
  </Step>

  <Step title="Add model parameters">
    Use **Model Parameters** for provider-specific JSON. These parameters are merged into the request after standard `model.*` keys.
  </Step>
</Steps>

***

## Compatibility values

| `apiCompatibility` value  | Endpoint shape                                                         | Runtime status                                                  |
| ------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
| `openai_chat_completions` | OpenAI Chat Completions compatible, usually `/v1/chat/completions`     | Supported                                                       |
| `openai_compatible`       | OpenAI-compatible chat servers such as vLLM, Ollama, LM Studio, or TGI | Supported                                                       |
| `openai_responses`        | OpenAI Responses compatible, usually `/v1/responses`                   | Supported                                                       |
| `anthropic_messages`      | Anthropic Messages, usually `/v1/messages`                             | Credential option exists, chat execution is not implemented yet |
| `gemini_generate_content` | Gemini `generateContent`                                               | Credential option exists, chat execution is not implemented yet |

If `apiCompatibility` is omitted, `integration-api` defaults to `openai_chat_completions`.

***

## Credential arguments

| Field              | Required | Type                    | Description                                                                                                                                             |
| ------------------ | -------: | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiCompatibility` |      Yes | `string`                | Selects the request/stream implementation. Use one of the compatibility values above.                                                                   |
| `baseUrl`          |      Yes | `string`                | Base URL passed to the HTTP client. For OpenAI-compatible servers, include the API root expected by the server, for example `http://localhost:8000/v1`. |
| `headers`          |       No | object of string values | Request headers. Use this for `Authorization`, provider routing headers, tenant IDs, or local server keys.                                              |

Example credential value:

```json theme={null}
{
  "apiCompatibility": "openai_chat_completions",
  "baseUrl": "https://llm.example.com/v1",
  "headers": {
    "Authorization": "Bearer sk_example"
  }
}
```

***

## Model arguments

| Option key         | Required | Description                                                                                         |
| ------------------ | -------: | --------------------------------------------------------------------------------------------------- |
| `model.id`         |      Yes | UI model selector value. For custom models, this can be any non-empty model/deployment ID.          |
| `model.name`       |      Yes | Model ID sent to the provider. Usually the same value as `model.id`.                                |
| `model.parameters` |       No | JSON object containing extra provider options. Merged into the request after direct `model.*` keys. |

Example model parameters:

```json theme={null}
{
  "temperature": 0.7,
  "max_tokens": 512,
  "top_p": 0.9
}
```

You can also pass direct `model.*` metadata keys. For example, `model.temperature` becomes `temperature` in the provider request.

***

## Supported request parameters

For `openai_chat_completions` and `openai_compatible`, these keys are mapped to first-class Chat Completions fields when possible:

| Parameter                                                | Type                    | Description                                                                    |
| -------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |
| `model.name`                                             | `string`                | Model name sent as `model`.                                                    |
| `temperature` or `model.temperature`                     | `number`                | Sampling temperature.                                                          |
| `top_p` or `model.top_p`                                 | `number`                | Nucleus sampling value.                                                        |
| `max_tokens` or `model.max_tokens`                       | `number`                | Maximum output tokens.                                                         |
| `max_completion_tokens` or `model.max_completion_tokens` | `number`                | Maximum completion tokens.                                                     |
| `frequency_penalty` or `model.frequency_penalty`         | `number`                | Frequency penalty.                                                             |
| `presence_penalty` or `model.presence_penalty`           | `number`                | Presence penalty.                                                              |
| `seed` or `model.seed`                                   | `number`                | Deterministic sampling seed.                                                   |
| `stop` or `model.stop`                                   | `string[]`              | Stop sequences.                                                                |
| `tool_choice` or `model.tool_choice`                     | `string`                | `auto`, `required`, or `none`. Applied only when tools are present.            |
| `response_format` or `model.response_format`             | object                  | `{"type":"json_object"}`, `{"type":"text"}`, or `{"type":"json_schema", ...}`. |
| `reasoning_effort` or `model.reasoning_effort`           | `string`                | Reasoning effort for compatible models.                                        |
| `user` or `model.user`                                   | `string`                | End-user identifier.                                                           |
| `metadata` or `model.metadata`                           | object of string values | Provider metadata.                                                             |
| `top_logprobs` or `model.top_logprobs`                   | `number`                | Number of top log probabilities.                                               |

Unknown parameters are passed as extra request fields. Use `model.parameters` for provider-specific fields such as `top_k` or `chat_template_kwargs`.

For `openai_responses`, these keys are mapped when possible:

| Parameter                                                     | Type                    | Description                                                          |
| ------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------- |
| `model.name`                                                  | `string`                | Model name sent as `model`.                                          |
| `temperature` / `model.temperature`                           | `number`                | Sampling temperature.                                                |
| `top_p` / `model.top_p`                                       | `number`                | Nucleus sampling value.                                              |
| `max_output_tokens`, `max_completion_tokens`, or `max_tokens` | `number`                | Maximum output tokens.                                               |
| `store` / `model.store`                                       | `boolean`               | Whether the provider should store the response. Defaults to `false`. |
| `tool_choice` / `model.tool_choice`                           | `string`                | `auto`, `required`, or `none`. Applied only when tools are present.  |
| `response_format` / `model.response_format`                   | object                  | Maps to Responses text format.                                       |
| `reasoning_effort` / `model.reasoning_effort`                 | `string`                | Reasoning effort.                                                    |
| `service_tier` / `model.service_tier`                         | `string`                | Provider service tier.                                               |
| `user` / `model.user`                                         | `string`                | End-user identifier.                                                 |
| `metadata` / `model.metadata`                                 | object of string values | Provider metadata.                                                   |
| `top_logprobs` / `model.top_logprobs`                         | `number`                | Number of top log probabilities.                                     |

***

## Examples

### OpenAI-compatible server

Credential:

```json theme={null}
{
  "apiCompatibility": "openai_compatible",
  "baseUrl": "http://localhost:8000/v1",
  "headers": {
    "Authorization": "Bearer local-dev-key"
  }
}
```

Assistant model:

```json theme={null}
{
  "model.id": "meta-llama/Llama-3.1-8B-Instruct",
  "model.name": "meta-llama/Llama-3.1-8B-Instruct",
  "model.parameters": {
    "temperature": 0.4,
    "max_tokens": 400,
    "top_k": 40
  }
}
```

### OpenAI Responses compatible server

Credential:

```json theme={null}
{
  "apiCompatibility": "openai_responses",
  "baseUrl": "https://api.openai.com/v1",
  "headers": {
    "Authorization": "Bearer sk_example"
  }
}
```

Assistant model:

```json theme={null}
{
  "model.id": "gpt-4.1-mini",
  "model.name": "gpt-4.1-mini",
  "model.parameters": {
    "max_output_tokens": 512,
    "reasoning_effort": "low",
    "store": false
  }
}
```

***

## Backend mapping

`integration-api` resolves `custom-llm` in `api/integration-api/internal/caller/caller.go`. Chat and streaming requests route through `api/integration-api/internal/caller/custom_llm`.

The credential parser validates:

* `baseUrl` is present and non-empty.
* `apiCompatibility` is a non-empty string when provided.
* `headers` is a string map when provided.

<CardGroup>
  <Card title="LLM overview" icon="network" href="/opensource/services/integration-api/llm/overview">
    Caller interfaces and model options.
  </Card>

  <Card title="Custom STT" icon="audio-waveform" href="/opensource/services/assistant-api/stt/custom">
    Configure custom speech-to-text.
  </Card>
</CardGroup>


# Google Gemini
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/gemini

Configure Google Gemini models in integration-api.

The Gemini caller uses the Google Generative AI Go SDK with streaming support.

**Provider directory:** `api/integration-api/internal/caller/gemini/`

***

## Vault Credential

| Key   | Description                                                                                 |
| ----- | ------------------------------------------------------------------------------------------- |
| `key` | Google AI Studio API key from [aistudio.google.com](https://aistudio.google.com/app/apikey) |

***

## Setup

<Steps>
  <Step title="Get a Gemini API key">
    Sign in at [aistudio.google.com](https://aistudio.google.com/app/apikey) → **Get API key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **Gemini**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant LLM">
    In the assistant settings → **LLM Provider**, select **Gemini** and set model parameters:

    ```json theme={null}
    {
      "model.name": "gemini-2.0-flash",
      "model.temperature": 0.7,
      "model.max_tokens": 512
    }
    ```
  </Step>
</Steps>

***

## Supported Models

| Model              | Context | Notes                          |
| ------------------ | ------- | ------------------------------ |
| `gemini-2.0-flash` | 1M      | Fastest, recommended for voice |
| `gemini-1.5-pro`   | 2M      | Largest context window         |
| `gemini-1.5-flash` | 1M      | Fast, low cost                 |
| `gemini-pro`       | 32k     | Legacy                         |

***

## Model Parameters

| Key                       | Supported | Notes                                       |
| ------------------------- | --------- | ------------------------------------------- |
| `model.name`              | ✅         | Required                                    |
| `model.temperature`       | ✅         | 0.0–2.0                                     |
| `model.max_tokens`        | ✅         |                                             |
| `model.top_p`             | ✅         |                                             |
| `model.top_k`             | ✅         | Gemini-specific                             |
| `model.stop`              | ✅         |                                             |
| `model.frequency_penalty` | ✅         |                                             |
| `model.presence_penalty`  | ✅         |                                             |
| `model.seed`              | ✅         |                                             |
| `model.response_format`   | ✅         | MIME type: `application/json`, `text/plain` |

***

<CardGroup>
  <Card title="OpenAI" icon="sparkles" href="/opensource/services/integration-api/llm/openai">
    GPT-4o models
  </Card>

  <Card title="LLM Overview" icon="network" href="/opensource/services/integration-api/llm/overview">
    All providers and ChatCompletionOptions
  </Card>
</CardGroup>


# OpenAI
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/openai

Configure OpenAI GPT models in integration-api.

The OpenAI caller uses the OpenAI Go SDK. Credentials are read from the vault. Streaming uses Server-Sent Events with per-token `onStream` callbacks.

**Provider directory:** `api/integration-api/internal/caller/openai/`

***

## Vault Credential

| Key   | Description                                                                              |
| ----- | ---------------------------------------------------------------------------------------- |
| `key` | OpenAI API key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |

***

## Setup

<Steps>
  <Step title="Get an OpenAI API key">
    Sign in at [platform.openai.com](https://platform.openai.com) → **API Keys → Create new secret key**.
  </Step>

  <Step title="Add to Rapida vault">
    In the Rapida dashboard → **Credentials → Create Credential**, select provider **OpenAI**, enter `key` = your API key.
  </Step>

  <Step title="Configure the assistant LLM">
    In the assistant settings → **LLM Provider**, select **OpenAI** and set model parameters:

    ```json theme={null}
    {
      "model.name": "gpt-4o",
      "model.temperature": 0.7,
      "model.max_tokens": 200,
      "model.tool_choice": "auto"
    }
    ```
  </Step>
</Steps>

***

## Supported Models

| Model           | Context | Notes                                |
| --------------- | ------- | ------------------------------------ |
| `gpt-4o`        | 128k    | Best balance of speed and capability |
| `gpt-4o-mini`   | 128k    | Fastest, lowest cost                 |
| `gpt-4-turbo`   | 128k    | High-capability                      |
| `gpt-4`         | 8k      | Legacy                               |
| `gpt-3.5-turbo` | 16k     | Low cost                             |

***

## Model Parameters

| Key                       | Supported | Notes                                     |
| ------------------------- | --------- | ----------------------------------------- |
| `model.name`              | ✅         | Required                                  |
| `model.temperature`       | ✅         | 0.0–2.0                                   |
| `model.max_tokens`        | ✅         |                                           |
| `model.top_p`             | ✅         |                                           |
| `model.stop`              | ✅         | Array of stop sequences                   |
| `model.tool_choice`       | ✅         | `auto`, `none`, `required`                |
| `model.frequency_penalty` | ✅         | -2.0–2.0                                  |
| `model.presence_penalty`  | ✅         | -2.0–2.0                                  |
| `model.seed`              | ✅         | Deterministic output                      |
| `model.response_format`   | ✅         | `json_object`, `text`                     |
| `model.reasoning_effort`  | ✅         | `low`, `medium`, `high` (o-series models) |

***

<CardGroup>
  <Card title="Anthropic" icon="bot" href="/opensource/services/integration-api/llm/anthropic">
    Claude models
  </Card>

  <Card title="LLM Overview" icon="network" href="/opensource/services/integration-api/llm/overview">
    All providers and ChatCompletionOptions
  </Card>
</CardGroup>


# LLM Providers — Overview
Source: https://doc.rapida.ai/opensource/services/integration-api/llm/overview

LargeLanguageCaller interface, ChatCompletionOptions, and supported LLM providers in integration-api.

The `integration-api` abstracts all LLM providers behind a single `LargeLanguageCaller` interface. Provider credentials are encrypted at rest using `INTEGRATION_CRYPTO_KEY`. The `assistant-api` calls integration-api via gRPC to execute LLM inference.

***

## `LargeLanguageCaller` Interface

Every LLM provider implements:

```go theme={null}
// api/integration-api/internal/caller/
type LargeLanguageCaller interface {
    // GetChatCompletion returns a complete response (non-streaming).
    GetChatCompletion(
        ctx         context.Context,
        messages    []ChatMessage,
        opts        ChatCompletionOptions,
        credentials map[string]interface{},
    ) (*ChatCompletion, error)

    // StreamChatCompletion streams tokens via callbacks.
    StreamChatCompletion(
        ctx         context.Context,
        messages    []ChatMessage,
        opts        ChatCompletionOptions,
        credentials map[string]interface{},
        onStream    func(token string),              // called per token
        onMetrics   func(metrics LLMMetrics),        // called on completion with token counts
        onError     func(err error),                 // called on error
    ) error
}
```

***

## `ChatCompletionOptions`

Model behaviour is controlled via the `ModelParameter` map:

```go theme={null}
type ChatCompletionOptions struct {
    ModelParameter map[string]interface{}  // keyed by "model.*"
    Tools          []ToolDefinition
}
```

| Key                       | Type       | Description                                   |
| ------------------------- | ---------- | --------------------------------------------- |
| `model.name`              | `string`   | Model ID (e.g. `gpt-4o`, `claude-sonnet-4-6`) |
| `model.temperature`       | `float`    | Sampling temperature (0.0–2.0)                |
| `model.max_tokens`        | `int`      | Maximum tokens in the response                |
| `model.top_p`             | `float`    | Nucleus sampling threshold                    |
| `model.stop`              | `[]string` | Stop sequences                                |
| `model.tool_choice`       | `string`   | Tool usage: `auto`, `none`, `required`        |
| `model.frequency_penalty` | `float`    | Repeat penalty (OpenAI / Gemini)              |
| `model.presence_penalty`  | `float`    | Topic penalty (OpenAI / Gemini)               |
| `model.seed`              | `int`      | Deterministic sampling seed                   |
| `model.response_format`   | `string`   | Output format (e.g. `json_object`)            |

Not all providers support all keys — unsupported keys are silently ignored.

***

## Supported LLM Providers

| Provider          | Directory             | Notes                            |
| ----------------- | --------------------- | -------------------------------- |
| **OpenAI**        | `caller/openai/`      | GPT-4o, GPT-4o-mini, GPT-4-turbo |
| **Anthropic**     | `caller/anthropic/`   | Claude Opus/Sonnet/Haiku         |
| **Google Gemini** | `caller/gemini/`      | Gemini 2.0, 1.5 Pro              |
| **Azure OpenAI**  | `caller/azure/`       | Azure-hosted OpenAI deployments  |
| **Mistral**       | `caller/mistral/`     | Mistral Large, Small, Nemo       |
| **Cohere**        | `caller/cohere/`      | Command R, Command R+            |
| **Vertex AI**     | `caller/vertexai/`    | Google Vertex AI models          |
| **HuggingFace**   | `caller/huggingface/` | HuggingFace Inference API        |
| **Replicate**     | `caller/replicate/`   | Replicate hosted models          |
| **Voyage AI**     | `caller/voyageai/`    | Embedding and reranking          |

***

## Credential Encryption

All vault credentials are encrypted with `INTEGRATION_CRYPTO_KEY` before storage. Never commit this key or expose it in logs.

```env theme={null}
# docker/integration-api/.integration.env
INTEGRATION_CRYPTO_KEY=32-char-random-string
```

***

## Provider Pages

<CardGroup>
  <Card title="OpenAI" icon="sparkles" href="/opensource/services/integration-api/llm/openai">
    GPT-4o, GPT-4o-mini
  </Card>

  <Card title="Anthropic" icon="bot" href="/opensource/services/integration-api/llm/anthropic">
    Claude Opus, Sonnet, Haiku
  </Card>

  <Card title="Gemini" icon="globe" href="/opensource/services/integration-api/llm/gemini">
    Gemini 2.0 Flash, 1.5 Pro
  </Card>

  <Card title="Azure OpenAI" icon="cloud" href="/opensource/services/integration-api/llm/azure">
    Azure-hosted OpenAI deployments
  </Card>

  <Card title="Configure Your Own" icon="code" href="/opensource/services/integration-api/llm/custom">
    Implement the LargeLanguageCaller interface
  </Card>
</CardGroup>


# Integration API
Source: https://doc.rapida.ai/opensource/services/integration-api/overview

Provider execution layer. Manages encrypted credential storage and executes all external AI provider calls on behalf of assistant-api.

## Purpose

The `integration-api` is the single point of contact with every external AI provider in the platform. It:

* Stores provider API keys encrypted at rest using AES-256-GCM
* Decrypts credentials in-memory per request (never written to logs or disk)
* Executes LLM streaming and non-streaming inference
* Generates embeddings for RAG search
* Verifies provider credentials before saving them

<CardGroup>
  <Card title="Port" icon="server">
    `9004` — HTTP · gRPC (cmux)
  </Card>

  <Card title="Language" icon="code">
    Go 1.25
    Gin (REST) + gRPC
  </Card>

  <Card title="Storage" icon="database">
    PostgreSQL `integration_db`
    Redis (provider cache)
  </Card>
</CardGroup>

<Info>
  `integration-api` is the **only** service that decrypts and uses provider API keys. Keys are decrypted in-memory per request and are never written to logs, forwarded to other services, or stored in plaintext anywhere.
</Info>

***

## Credential Encryption Flow

```mermaid theme={null}
sequenceDiagram
    participant UI as Dashboard
    participant Web as web-api :9001
    participant Integ as integration-api :9004
    participant PG as PostgreSQL (integration_db)
    participant LLM as LLM Provider

    UI->>Web: Save OpenAI API key
    Web->>Integ: gRPC CreateCredential(key, project_id)
    Integ->>Integ: AES-256-GCM encrypt(key, INTEGRATION_CRYPTO_KEY)
    Integ->>PG: INSERT encrypted_credential
    Note over PG: Plaintext key never stored

    Note over Integ,LLM: At call time (called by assistant-api)
    Integ->>PG: SELECT encrypted_credential WHERE id = ?
    Integ->>Integ: Decrypt in-memory
    Integ->>LLM: API call with plaintext key
    Note over Integ: Key discarded after call
```

***

## Supported Providers

<Tabs>
  <Tab title="LLM">
    | Provider         | Notes                                                 |
    | ---------------- | ----------------------------------------------------- |
    | OpenAI           | GPT-4o, GPT-4, GPT-3.5 · Function calling · Streaming |
    | Anthropic        | Claude 3.5 Sonnet, Claude 3 · Tool use · Streaming    |
    | Google Gemini    | Gemini Pro · Flash · Streaming                        |
    | Google Vertex AI | Enterprise Gemini deployment                          |
    | Azure OpenAI     | Enterprise GPT with custom endpoint                   |
    | AWS Bedrock      | Llama, Titan, Mistral via AWS                         |
    | Cohere           | Command R+ · Streaming                                |
    | Mistral          | Mistral Large · Small · Streaming                     |
    | HuggingFace      | Inference API                                         |
    | Replicate        | Model hosting                                         |
    | VoyageAI         | Embeddings and reranking                              |
  </Tab>

  <Tab title="STT">
    | Provider                 | Notes                                  |
    | ------------------------ | -------------------------------------- |
    | Google Cloud STT         | Streaming, 100+ languages              |
    | Azure Cognitive Services | Neural Speech, real-time               |
    | Deepgram                 | Nova-2 / Nova-3, low-latency streaming |
    | AssemblyAI               | Streaming and batch                    |
    | Cartesia                 | Real-time                              |
    | Sarvam AI                | Indian languages                       |
  </Tab>

  <Tab title="TTS">
    | Provider                 | Notes                         |
    | ------------------------ | ----------------------------- |
    | Google Cloud TTS         | WaveNet / Neural2             |
    | Azure Cognitive Services | Neural voices, 140+ languages |
    | ElevenLabs               | High-fidelity voice cloning   |
    | Deepgram Aura            | Fast synthesis                |
    | Cartesia                 | Streaming synthesis           |
    | Sarvam AI                | Indian languages              |
  </Tab>

  <Tab title="Telephony">
    | Provider | Notes                                           |
    | -------- | ----------------------------------------------- |
    | Twilio   | Programmable Voice, Media Streams, bulk calling |
    | Vonage   | Voice API, WebSocket audio                      |
    | Exotel   | Cloud telephony — India / SEA                   |
  </Tab>
</Tabs>

***

## Caller Architecture

Each LLM provider lives under `api/integration-api/internal/caller/<provider>/`. The directory structure is:

```
api/integration-api/internal/caller/
├── callers.go              ← interfaces + factory
├── chat_options.go         ← ChatCompletionOptions, ToolDefinition
├── embedding_options.go    ← EmbeddingOptions
├── reranking_options.go    ← RerankerOptions
├── anthropic/
├── azure/
├── cohere/
├── gemini/
├── huggingface/
├── mistral/
├── openai/                 ← reference implementation
├── replicate/
├── vertexai/
└── voyageai/
```

Each provider package contains:

| File                   | Purpose                                   |
| ---------------------- | ----------------------------------------- |
| `<provider>.go`        | Client initialization, credential binding |
| `llm.go`               | `LargeLanguageCaller` implementation      |
| `embedding.go`         | `EmbeddingCaller` (where supported)       |
| `verify-credential.go` | Pre-storage credential validation         |

***

## Running

<Tabs>
  <Tab title="Docker Compose">
    ```bash theme={null}
    make up-integration

    make logs-integration

    make rebuild-integration
    ```
  </Tab>

  <Tab title="From Source">
    Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.

    ```bash theme={null}
    export $(grep -v '^#' docker/integration-api/.integration.env | xargs)
    export POSTGRES__HOST=localhost
    export REDIS__HOST=localhost
    export WEB_HOST=localhost:9001

    go run cmd/integration/integration.go
    ```
  </Tab>
</Tabs>

***

## Health Endpoints

| Endpoint          | Purpose                              |
| ----------------- | ------------------------------------ |
| `GET /readiness/` | Service ready (DB + Redis connected) |
| `GET /healthz/`   | Liveness probe                       |

```bash theme={null}
curl http://localhost:9004/readiness/
```

***

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/opensource/services/integration-api/configuration">
    Environment variables including INTEGRATION\_CRYPTO\_KEY.
  </Card>

  <Card title="Adding Providers" icon="plug" href="/opensource/services/integration-api/providers">
    LargeLanguageCaller interface and how to add a new LLM provider.
  </Card>

  <Card title="Assistant API" icon="mic" href="/opensource/services/assistant-api/overview">
    How assistant-api calls integration-api during a live voice conversation.
  </Card>

  <Card title="Architecture" icon="network" href="/opensource/architecture">
    Full system topology.
  </Card>
</CardGroup>


# Web API — Configuration
Source: https://doc.rapida.ai/opensource/services/web-api/configuration

Complete environment variable reference for the web-api service.

## Configuration File

Edit `docker/web-api/.web.env` before starting the service.

***

## Required Variables

| Variable                   | Default                    | Description                                                |
| -------------------------- | -------------------------- | ---------------------------------------------------------- |
| `SECRET`                   | `rpd_pks`                  | JWT signing secret — must be identical across all services |
| `POSTGRES__HOST`           | `postgres`                 | PostgreSQL host                                            |
| `POSTGRES__DB_NAME`        | `web_db`                   | Database name                                              |
| `POSTGRES__AUTH__USER`     | `rapida_user`              | Database user                                              |
| `POSTGRES__AUTH__PASSWORD` | —                          | Database password                                          |
| `REDIS__HOST`              | `redis`                    | Redis host                                                 |
| `INTEGRATION_HOST`         | `integration-api:9004`     | integration-api gRPC address                               |
| `ENDPOINT_HOST`            | `endpoint-api:9005`        | endpoint-api gRPC address                                  |
| `ASSISTANT_HOST`           | `assistant-api:9007`       | assistant-api gRPC address                                 |
| `DOCUMENT_HOST`            | `http://document-api:9010` | document-api HTTP address                                  |

<Warning>
  `SECRET` is used for both JWT signing and credential vault encryption. All services must share the same value. Changing it in production will invalidate all active sessions and make stored vault credentials unreadable. Rotate carefully.
</Warning>

***

## Service Identity

| Variable       | Default       | Description                              |
| -------------- | ------------- | ---------------------------------------- |
| `SERVICE_NAME` | `web-api`     | Internal service label                   |
| `HOST`         | `0.0.0.0`     | Bind address                             |
| `PORT`         | `9001`        | HTTP / gRPC / gRPC-web port              |
| `LOG_LEVEL`    | `debug`       | `debug` · `info` · `warn` · `error`      |
| `ENV`          | `development` | `development` · `staging` · `production` |

***

## PostgreSQL

| Variable                              | Default              | Description                            |
| ------------------------------------- | -------------------- | -------------------------------------- |
| `POSTGRES__HOST`                      | `postgres`           | Host (`localhost` for local dev)       |
| `POSTGRES__PORT`                      | `5432`               | Port                                   |
| `POSTGRES__DB_NAME`                   | `web_db`             | Database name                          |
| `POSTGRES__AUTH__USER`                | `rapida_user`        | User                                   |
| `POSTGRES__AUTH__PASSWORD`            | `rapida_db_password` | Password                               |
| `POSTGRES__MAX_OPEN_CONNECTION`       | `10`                 | Connection pool size                   |
| `POSTGRES__MAX_IDEAL_CONNECTION`      | `10`                 | Idle connections                       |
| `POSTGRES__SSL_MODE`                  | `disable`            | `disable` · `require` · `verify-full`  |
| `POSTGRES__SLC_CACHE__HOST`           | `redis`              | Redis host for second-level GORM cache |
| `POSTGRES__SLC_CACHE__PORT`           | `6379`               | Redis port for GORM cache              |
| `POSTGRES__SLC_CACHE__DB`             | `1`                  | Redis DB index for GORM cache          |
| `POSTGRES__SLC_CACHE__MAX_CONNECTION` | `10`                 | Redis pool size                        |

***

## Redis

| Variable                | Default | Description                            |
| ----------------------- | ------- | -------------------------------------- |
| `REDIS__HOST`           | `redis` | Redis host (`localhost` for local dev) |
| `REDIS__PORT`           | `6379`  | Redis port                             |
| `REDIS__MAX_CONNECTION` | `5`     | Connection pool size                   |

***

## Asset Storage

| Variable                           | Default                       | Description              |
| ---------------------------------- | ----------------------------- | ------------------------ |
| `ASSET_STORE__STORAGE_TYPE`        | `local`                       | `local` · `s3` · `azure` |
| `ASSET_STORE__STORAGE_PATH_PREFIX` | `/app/rapida-data/assets/web` | Path for local storage   |

***

## Internal Service Addresses

| Variable           | Default                    | Description                                               |
| ------------------ | -------------------------- | --------------------------------------------------------- |
| `INTEGRATION_HOST` | `integration-api:9004`     | integration-api gRPC (`localhost:9004` for local dev)     |
| `ENDPOINT_HOST`    | `endpoint-api:9005`        | endpoint-api gRPC (`localhost:9005` for local dev)        |
| `ASSISTANT_HOST`   | `assistant-api:9007`       | assistant-api gRPC (`localhost:9007` for local dev)       |
| `WEB_HOST`         | `web-api:9001`             | Self-reference for intra-service gRPC                     |
| `DOCUMENT_HOST`    | `http://document-api:9010` | document-api HTTP (`http://localhost:9010` for local dev) |
| `UI_HOST`          | `https://localhost:3000`   | Dashboard UI origin (used for OAuth redirect validation)  |

***

## Full Environment File

```env theme={null}
# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=web-api
HOST=0.0.0.0
PORT=9001
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__PORT=5432
POSTGRES__DB_NAME=web_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__MAX_OPEN_CONNECTION=10
POSTGRES__MAX_IDEAL_CONNECTION=10
POSTGRES__SSL_MODE=disable

# ── Redis (second-level GORM cache) ───────────────────────────────
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__DB=1
POSTGRES__SLC_CACHE__MAX_CONNECTION=10

# ── Redis ─────────────────────────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=5

# ── Asset storage ─────────────────────────────────────────────────
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/web

# ── Internal service addresses ────────────────────────────────────
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
DOCUMENT_HOST=http://document-api:9010
UI_HOST=https://localhost:3000
```

***

## Next Steps

<CardGroup>
  <Card title="Overview" icon="server" href="/opensource/services/web-api/overview">
    Web API purpose, request flow, and component architecture.
  </Card>

  <Card title="Configuration Reference" icon="sliders" href="/opensource/configuration">
    Cross-service configuration reference.
  </Card>
</CardGroup>


# Web API
Source: https://doc.rapida.ai/opensource/services/web-api/overview

Core platform backend. Handles authentication, organization management, credential vault, and acts as the gRPC proxy for all dashboard operations.

## Purpose

The `web-api` is the primary API backend for the Rapida dashboard. Every request from the browser — authentication, organization setup, assistant management, credential storage — goes through this service. It also acts as the gRPC proxy for downstream services, validating JWT tokens before forwarding requests.

<CardGroup>
  <Card title="Port" icon="server">
    `9001` — HTTP · gRPC · gRPC-web (cmux)
  </Card>

  <Card title="Language" icon="code">
    Go 1.25
    Gin (REST) + gRPC
  </Card>

  <Card title="Storage" icon="database">
    PostgreSQL `web_db`
    Redis (session cache)
  </Card>
</CardGroup>

***

## Request Flow

```mermaid theme={null}
sequenceDiagram
    participant Browser as Browser (Dashboard)
    participant Nginx as Nginx :8080
    participant Web as web-api :9001
    participant PG as PostgreSQL (web_db)
    participant Redis as Redis
    participant DS as Downstream Service

    Browser->>Nginx: gRPC-web POST /<service>_api.*
    Nginx->>Web: Forward (all non-talk_api paths)
    Web->>Web: JWT interceptor — validate token
    Web->>PG: Check organization + project scope
    alt Local service
        Web->>PG: Execute operation
        Web->>Redis: Update cache
    else Downstream proxy
        Web->>DS: gRPC forward with org context
        DS-->>Web: Response
    end
    Web-->>Browser: gRPC-web response
```

***

## Core Components

<AccordionGroup>
  <Accordion title="Authentication & Session Management">
    Handles user registration, login, password recovery, OAuth 2.0, and JWT issuance.

    | Feature         | Detail                                                 |
    | --------------- | ------------------------------------------------------ |
    | Token type      | JWT (signed with `SECRET`, shared across all services) |
    | Token storage   | Client-side (`Authorization` header)                   |
    | Session cache   | Redis DB 1                                             |
    | OAuth providers | Google, GitHub, Microsoft (configured per deployment)  |
    | Token expiry    | Default 24 hours                                       |
  </Accordion>

  <Accordion title="Organization & Project Hierarchy">
    Every resource in Rapida is scoped to an `Organization → Project` hierarchy. The web-api enforces this at the gRPC interceptor level.

    ```
    Organization
    └── Project
        ├── Assistants
        ├── Knowledge Bases
        ├── Integrations
        └── Webhooks
    ```

    The gRPC auth interceptor rejects any request where the JWT's organization claim does not match the target resource's `organization_id`.
  </Accordion>

  <Accordion title="Credential Vault">
    Provider API keys are encrypted with AES-256-GCM before storage. The encryption key is derived from `SECRET`.

    | Operation    | Behavior                                                |
    | ------------ | ------------------------------------------------------- |
    | Store key    | AES-256-GCM encrypt → write to `web_db`                 |
    | Retrieve key | Read → decrypt in-memory → forward to `integration-api` |
    | Rotate key   | Replace ciphertext; in-flight calls unaffected          |
    | Audit        | Every read/write logged with user ID and timestamp      |
  </Accordion>

  <Accordion title="gRPC Proxy Routing">
    The web-api proxies all dashboard gRPC calls after JWT validation:

    | gRPC Path Prefix                                      | Forwarded To                                                          |
    | ----------------------------------------------------- | --------------------------------------------------------------------- |
    | `/web_api` · `/vault_api`                             | Local (web-api)                                                       |
    | `/workflow_api` · `/assistant_api` · `/knowledge_api` | `assistant-api:9007`                                                  |
    | `/tool_api` · `/endpoint_api` · `/webhook_api`        | `endpoint-api:9005`                                                   |
    | `/provider_api` · `/integration_api`                  | `integration-api:9004`                                                |
    | `/document_api`                                       | `document-api:9010`                                                   |
    | `/connect_api`                                        | Local (OAuth connector)                                               |
    | `/talk_api`                                           | **Direct to `assistant-api` via Nginx** — not proxied through web-api |
  </Accordion>

  <Accordion title="Database Migrations">
    Migrations run automatically at service startup using [golang-migrate](https://github.com/golang-migrate/migrate). Migration files are in `api/web-api/migrations/`:

    ```
    000001_initial_schema.up.sql
    000001_initial_schema.down.sql
    000002_add_oauth_tokens.up.sql
    ```

    To run migrations manually:

    ```bash theme={null}
    go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

    migrate \
      -path api/web-api/migrations \
      -database "postgresql://rapida_user:rapida_db_password@localhost:5432/web_db?sslmode=disable" \
      up
    ```
  </Accordion>
</AccordionGroup>

***

## Running

<Tabs>
  <Tab title="Docker Compose">
    ```bash theme={null}
    make up-web

    make logs-web

    make rebuild-web

    make shell-web
    ```
  </Tab>

  <Tab title="From Source">
    Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.

    ```bash theme={null}
    export $(grep -v '^#' docker/web-api/.web.env | xargs)
    export POSTGRES__HOST=localhost
    export REDIS__HOST=localhost
    export INTEGRATION_HOST=localhost:9004
    export ENDPOINT_HOST=localhost:9005
    export ASSISTANT_HOST=localhost:9007
    export DOCUMENT_HOST=http://localhost:9010

    go run cmd/web/web.go
    ```
  </Tab>
</Tabs>

***

## Health Endpoints

| Endpoint          | Purpose                              |
| ----------------- | ------------------------------------ |
| `GET /readiness/` | Service ready (DB + Redis connected) |
| `GET /healthz/`   | Liveness probe                       |

```bash theme={null}
curl http://localhost:9001/readiness/
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service exits immediately on startup">
    The most common cause is PostgreSQL not yet healthy.

    ```bash theme={null}
    docker compose ps postgres
    make logs-web | head -40
    ```
  </Accordion>

  <Accordion title="JWT validation fails across services">
    All services must share the same secret value. Confirm `secret` is identical in `docker/web-api/web.yml`, `docker/assistant-api/assistant.yml`, `docker/integration-api/integration.yml`, and `docker/endpoint-api/endpoint.yml`.
  </Accordion>

  <Accordion title="gRPC proxy returns 'service unavailable'">
    The target downstream service must be running and healthy. Verify `INTEGRATION_HOST`, `ENDPOINT_HOST`, `ASSISTANT_HOST` point to reachable addresses. Check `make status` to confirm all containers are `Up`.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/opensource/services/web-api/configuration">
    All environment variables and internal service addresses.
  </Card>

  <Card title="Assistant API" icon="mic" href="/opensource/services/assistant-api/overview">
    Voice orchestration service that web-api proxies to.
  </Card>

  <Card title="Integration API" icon="plug" href="/opensource/services/integration-api/overview">
    Provider credential management.
  </Card>

  <Card title="Architecture" icon="network" href="/opensource/architecture">
    Full system topology and routing.
  </Card>
</CardGroup>


# Web Console & UI
Source: https://doc.rapida.ai/opensource/services/web-console

Web dashboard and user interface for Rapida

**Service**: ui\
**Port**: 3000\
**Technology**: React + TypeScript + Tailwind CSS\
**Container**: Included in docker-compose.yml

## Purpose

The web console is the primary interface for:

* Creating and managing voice assistants
* Viewing and analyzing conversations
* Managing knowledge bases and documents
* Configuring credentials and integrations
* Monitoring performance and analytics
* Team collaboration and workspace management

## Key Features

### Assistant Management

* Create new voice assistants with flexible configuration
* Version control for assistant configurations
* Real-time testing and debugging
* Performance analytics and call metrics

### Conversation Viewer

* Search and filter conversations by date, agent, or keywords
* View complete conversation transcripts
* Listen to audio recordings
* Analyze conversation quality and metrics
* Export conversation data

### Knowledge Base Management

* Upload documents (PDF, DOCX, XLSX, CSV, MD, HTML)
* Manage document chunks and embeddings
* Full-text search across knowledge base
* Semantic search with similarity scores
* Document versioning and organization

### Integration Configuration

* Connect external AI providers (OpenAI, Anthropic, etc.)
* Configure STT/TTS services
* Manage telephony integrations (Twilio, Vonage, etc.)
* Secure credential storage with encryption
* Provider health monitoring

### Analytics & Monitoring

* Call duration and quality metrics
* LLM token usage and costs
* Response time analysis
* Error tracking and debugging
* Real-time conversation monitoring

### Team Management

* Multi-user workspace support
* Role-based access control
* Team member invitation
* Activity logging and audit trails

## Accessing the Dashboard

### Local Development

```bash theme={null}
# After starting services with Docker
open http://localhost:3000

# Or with manual setup
yarn start:dev
# Then navigate to http://localhost:3000
```

### Production Deployment

```
https://your-domain.com
# Through Nginx reverse proxy on port 8080
```

## Technology Stack

| Component       | Purpose             |
| --------------- | ------------------- |
| React 18+       | UI framework        |
| TypeScript      | Type safety         |
| Tailwind CSS    | Styling and theming |
| React Router    | Navigation          |
| Hooks & Context | State management    |
| WebSocket       | Real-time updates   |
| Axios           | API communication   |
| Material-UI     | Component library   |

## Environment Configuration

**File**: `.env.production` or `.env.development`

```env theme={null}
REACT_APP_API_URL=http://localhost:8080
REACT_APP_WS_URL=ws://localhost:8080
REACT_APP_ENV=development|production
```

## Build and Deployment

### Development Server

```bash theme={null}
cd ui
yarn install
yarn start:dev
```

Starts on `http://localhost:3000` with hot-reload.

### Production Build

```bash theme={null}
cd ui
yarn install
yarn build
```

Generates optimized build in `ui/build/`.

### Docker Deployment

```dockerfile theme={null}
# See docker/ui/Dockerfile
# Builds React app and serves via Nginx
```

```bash theme={null}
# Run with Docker
docker compose up ui

# Or build manually
docker build -f docker/ui/Dockerfile -t rapida-ui:latest .
docker run -p 3000:3000 rapida-ui:latest
```

## Frontend Architecture

### Directory Structure

```
ui/src/
├── index.tsx              # Entry point
├── app/
│   ├── index.tsx          # Root App component
│   ├── components/        # Reusable UI components
│   ├── pages/             # Page components
│   └── routes/            # Route definitions
├── configs/               # Configuration files
├── context/               # React Context providers
├── hooks/                 # Custom React hooks
├── icons/                 # Icon components
├── models/                # Type definitions
├── styles/                # Global styles
├── types/                 # TypeScript types
├── utils/                 # Helper functions
└── workspace/             # Workspace-specific features
```

### Key Components

**Authentication**

* Login/signup forms
* JWT token management
* OAuth integrations (Google, GitHub, etc.)
* Session management

**Assistant Management**

* Create assistant wizard
* Assistant list and detail views
* Version management
* Testing interface

**Conversation Viewer**

* Conversation list with filtering/search
* Message timeline with audio playback
* Transcript display with highlighting
* Metrics and analytics

**Knowledge Base**

* Document upload interface
* Knowledge base browser
* Chunk viewer and editor
* Search interface

**Integration Settings**

* Credential input forms
* Provider configuration
* API key management
* Connection testing

## Performance Optimization

### Code Splitting

* Lazy loading of route components
* Dynamic imports for heavy modules

### Caching

* Browser cache for static assets
* Redis caching on backend for API responses

### Bundling

* Minification and compression
* Tree shaking for unused code
* Asset optimization

## Development Workflow

### Setup Local Development

```bash theme={null}
cd ui

# Install dependencies
yarn install

# Start development server
yarn start:dev

# Run linting
yarn lint
yarn lint:fix

# Run tests
yarn test

# Build for production
yarn build

# Build Tailwind CSS
yarn build:css
```

### Debugging

```bash theme={null}
# Chrome DevTools
# F12 or Right-click → Inspect

# Source Maps
# Enabled in development, disabled in production

# Network Tab
# View API requests and responses

# React DevTools
# Browser extension for React debugging
```

## Styling

### Tailwind CSS

The UI uses Tailwind CSS for styling:

```bash theme={null}
# Watch mode (development)
yarn build:css

# One-time build (production)
yarn build:css
```

### Custom Styles

Global styles in:

* `src/styles/index.css`
* `src/styles/globals.css`

Component-specific styles in:

* `src/components/{Component}/{Component}.module.css`

## Troubleshooting

### Port 3000 Already in Use

```bash theme={null}
# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
PORT=3001 yarn start:dev
```

### Blank Page After Login

```bash theme={null}
# Clear browser cache
# Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)

# Check browser console for errors
# F12 → Console tab

# Check Network tab for failed requests
```

### API Connection Issues

```bash theme={null}
# Verify API is running (routes through Nginx to web-api)
curl http://localhost:9001/readiness/

# Check CORS headers
# Network tab → API request → Response Headers

# Verify REACT_APP_API_URL is correct
echo $REACT_APP_API_URL
```

## Next Steps

* [Web API Backend](/opensource/services/web-api)
* [Installation Guide](/opensource/installation)
* [Configuration](/opensource/configuration)


# Troubleshooting Guide
Source: https://doc.rapida.ai/opensource/troubleshooting

Solutions for common Rapida setup and runtime issues

### Installation Failed

**Problem**: Installation script or make command fails

**Solutions**:

1. **Check prerequisites are installed**:

   ```bash theme={null}
   go version
   docker --version
   docker compose version
   psql --version
   redis-cli --version
   ```

2. **Ensure proper permissions**:

   ```bash theme={null}
   # macOS/Linux
   mkdir -p ~/rapida-data/assets
   chmod -R 755 ~/rapida-data

   # Linux with Docker group
   sudo usermod -aG docker $USER
   newgrp docker
   ```

3. **Run setup command**:
   ```bash theme={null}
   make setup-local
   ```

### Database Connection Failed

**Problem**: Services can't connect to PostgreSQL

**Symptoms**:

* Error messages mentioning `connection refused`
* Services failing to start
* Logs showing database errors

**Solutions**:

1. **Verify PostgreSQL is running**:

   ```bash theme={null}
   # macOS
   brew services list | grep postgres

   # Linux
   sudo systemctl status postgresql

   # Or check directly
   psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"
   ```

2. **Check database credentials**:

   ```bash theme={null}
   # Verify user exists
   psql postgres -c "\du"

   # Verify databases exist
   psql postgres -c "\l"
   ```

3. **Check connection settings in .env**:

   ```bash theme={null}
   # Docker
   grep POSTGRES docker/web-api/.web.env

   # Manual setup
   grep POSTGRES env/.web.env
   ```

4. **Restart PostgreSQL**:

   ```bash theme={null}
   # macOS
   brew services restart postgresql

   # Linux
   sudo systemctl restart postgresql

   # Docker
   make down-db
   make up-db
   ```

5. **Check PostgreSQL logs**:

   ```bash theme={null}
   # Docker
   docker logs postgres

   # macOS
   tail -f /usr/local/var/log/postgres.log

   # Linux
   sudo tail -f /var/log/postgresql/postgresql.log
   ```

### Redis Connection Issues

**Problem**: Redis connection timeout or refused

**Symptoms**:

* Cache operations failing
* Session errors
* Redis connection refused messages

**Solutions**:

1. **Verify Redis is running**:

   ```bash theme={null}
   redis-cli ping
   # Should return: PONG
   ```

2. **Start Redis**:

   ```bash theme={null}
   # macOS
   brew services start redis

   # Linux
   sudo systemctl start redis-server

   # Docker
   make up-redis
   ```

3. **Check Redis logs**:

   ```bash theme={null}
   # Docker
   docker logs redis

   # Linux
   sudo tail -f /var/log/redis/redis-server.log
   ```

4. **Test Redis connection**:
   ```bash theme={null}
   redis-cli -h localhost -p 6379
   > ping
   PONG
   > exit
   ```

### OpenSearch Won't Start

**Problem**: OpenSearch container crashes or won't connect

**Symptoms**:

* Container immediately exits
* `curl: (7) Failed to connect to localhost port 9200`
* Out of memory errors

**Solutions**:

1. **Check resource limits**:

   ```bash theme={null}
   # OpenSearch requires 512MB minimum
   # Increase Docker memory allocation
   # Docker Desktop -> Preferences -> Resources -> Memory: 8GB

   # Or reduce allocation in docker-compose.yml:
   OPENSEARCH_JAVA_OPTS: "-Xms256m -Xmx256m"
   ```

2. **Check logs**:

   ```bash theme={null}
   docker logs opensearch
   ```

3. **Reset OpenSearch**:

   ```bash theme={null}
   # Docker
   make down-opensearch
   docker volume rm $(docker volume ls | grep opensearch | awk '{print $2}')
   make up-opensearch

   # Or manually
   rm -rf ~/rapida-data/assets/opensearch/*
   make up-opensearch
   ```

4. **Verify health**:

   ```bash theme={null}
   # Check cluster health
   curl -s http://localhost:9200/_cluster/health | jq .

   # Expected: "status": "green" or "yellow"
   ```

## Service Issues

### Service Won't Start

**Problem**: Service container exits immediately with error

**Symptoms**:

* Container exits after a few seconds
* Status shows "Exited (1)"
* Error logs in docker logs

**Solutions**:

1. **Check service logs**:

   ```bash theme={null}
   # Docker
   docker logs web-api

   # Manual setup
   # Check terminal where service was running
   ```

2. **Check port availability**:

   ```bash theme={null}
   # Find process using port
   lsof -i :9001

   # Kill process or change port
   kill -9 <PID>
   # Or edit docker-compose.yml/config
   ```

3. **Verify database is ready**:

   ```bash theme={null}
   # PostgreSQL must be running first
   psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"

   # If not ready, wait and retry
   make down-web
   sleep 10
   make up-web
   ```

4. **Check configuration**:

   ```bash theme={null}
   # Verify environment variables
   docker exec web-api env | grep POSTGRES

   # Check config syntax
   cat docker/web-api/.web.env
   ```

### Services Crashing After Startup

**Problem**: Services start but crash after a few minutes

**Symptoms**:

* Services in "Exited" state
* Intermittent crashes
* Error logs showing timeouts or connection issues

**Solutions**:

1. **Check resource constraints**:

   ```bash theme={null}
   # Monitor resource usage
   docker stats

   # If 100% CPU or memory, increase limits or optimize queries
   ```

2. **Check database connections**:

   ```bash theme={null}
   # Too many connections?
   psql -h localhost -U rapida_user -d web_db
   SELECT count(*) FROM pg_stat_activity;

   # Increase max connections
   ALTER SYSTEM SET max_connections = 200;
   ```

3. **Review logs for patterns**:

   ```bash theme={null}
   docker logs web-api --tail=100 -f

   # Look for patterns in error messages
   ```

### High Memory Usage

**Problem**: Services consuming excessive memory

**Solutions**:

1. **Check which service is consuming memory**:

   ```bash theme={null}
   docker stats
   ```

2. **For OpenSearch** (common culprit):

   ```bash theme={null}
   # Reduce memory allocation
   # Edit docker-compose.yml
   OPENSEARCH_JAVA_OPTS: "-Xms256m -Xmx256m"

   # Restart
   docker compose restart opensearch
   ```

3. **For PostgreSQL**:

   ```bash theme={null}
   # Check for slow queries
   psql -h localhost -U rapida_user -d web_db
   SELECT query, calls, total_time FROM pg_stat_statements
   ORDER BY total_time DESC LIMIT 10;
   ```

4. **General troubleshooting**:

   ```bash theme={null}
   # Restart affected service
   docker compose restart web-api

   # Clean up unused data
   docker system prune -a
   ```

## Network Issues

### Cannot Access Services

**Problem**: Services are running but not responding to requests

**Symptoms**:

* `curl: (7) Failed to connect`
* `Connection refused`
* Services ping but don't respond

**Solutions**:

1. **Verify services are running**:

   ```bash theme={null}
   docker ps | grep rapida
   # All services should show "Up"
   ```

2. **Check port bindings**:

   ```bash theme={null}
   # Verify ports are mapped
   docker port web-api
   # Should show: 9001/tcp -> 0.0.0.0:9001
   ```

3. **Test network connectivity**:

   ```bash theme={null}
   # From host
   curl http://localhost:9001/readiness/

   # If fails, check if service is responsive
   docker exec web-api curl http://localhost:9001/readiness/
   ```

4. **Check firewall**:

   ```bash theme={null}
   # macOS
   sudo lsof -i :9001

   # Linux
   sudo netstat -tlnp | grep 9001
   ```

5. **Verify DNS resolution**:
   ```bash theme={null}
   # Check service name resolution in Docker
   docker exec web-api ping postgres
   docker exec web-api ping redis
   docker exec web-api ping opensearch
   ```

### Services Can't Communicate

**Problem**: Services running but can't reach each other

**Symptoms**:

* Service logs showing "host not found"
* Connection timeouts between services
* Integration failures

**Solutions**:

1. **Verify network**:

   ```bash theme={null}
   # Check if services on same network
   docker network ls
   docker network inspect api-network
   ```

2. **Test service-to-service connectivity**:

   ```bash theme={null}
   # From web-api container
   docker exec web-api curl http://assistant-api:9007/readiness/

   # Check DNS resolution
   docker exec web-api nslookup assistant-api
   ```

3. **Check Docker Compose**:

   ```bash theme={null}
   # Ensure services are on api-network
   grep "networks:" docker-compose.yml
   grep "api-network" docker-compose.yml
   ```

4. **Recreate network**:
   ```bash theme={null}
   docker compose down
   docker network rm api-network
   docker compose up -d
   ```

## Data Issues

### Lost Data After Restart

**Problem**: Data disappeared after stopping/restarting containers

**Solutions**:

1. **Verify volumes are properly mounted**:

   ```bash theme={null}
   # Check volume mounts
   docker inspect postgres | grep -A 5 Mounts

   # Should show volume mount to ~/rapida-data/assets/db
   ```

2. **Check Docker Compose volume configuration**:

   ```bash theme={null}
   # Verify volumes section
   grep -A 20 "volumes:" docker-compose.yml | head -20
   ```

3. **Ensure data directory exists**:

   ```bash theme={null}
   ls -la ~/rapida-data/assets/
   # Should show: db/, redis/, opensearch/ directories
   ```

4. **Backup and restore data**:

   ```bash theme={null}
   # Backup PostgreSQL
   docker compose exec postgres pg_dump -U rapida_user web_db > backup.sql

   # Restore
   docker compose exec -T postgres psql -U rapida_user web_db < backup.sql
   ```

### Database Corruption

**Problem**: Database reports corruption or inconsistency

**Symptoms**:

* Strange SQL errors
* Data appearing corrupted
* Ability to read but not write

**Solutions**:

1. **Check database integrity**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   SELECT pg_database.datname, pg_database_size(pg_database.datname)
   FROM pg_database;
   ```

2. **VACUUM and ANALYZE**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   VACUUM FULL;
   ANALYZE;
   ```

3. **Rebuild indexes**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   REINDEX DATABASE web_db;
   ```

4. **Full restoration**:

   ```bash theme={null}
   # Stop services
   make down-all

   # Backup current data
   cp -r ~/rapida-data/assets/db ~/rapida-data/assets/db.backup

   # Reset database
   rm -rf ~/rapida-data/assets/db/*

   # Start and restore
   make up-db
   # Wait for initialization
   docker compose exec -T postgres psql -U rapida_user web_db < backup.sql
   ```

## Performance Issues

### Slow API Responses

**Problem**: API endpoints responding slowly

**Solutions**:

1. **Check database performance**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   SELECT query, calls, total_time FROM pg_stat_statements
   ORDER BY total_time DESC LIMIT 10;
   ```

2. **Monitor resource usage**:

   ```bash theme={null}
   docker stats

   # If CPU/memory at limit, need to optimize or increase
   ```

3. **Check query plans**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   EXPLAIN ANALYZE SELECT * FROM conversations WHERE id = '123';
   ```

4. **Create missing indexes**:

   ```bash theme={null}
   # Common queries to index:
   CREATE INDEX idx_conversations_user_id ON conversations(user_id);
   CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
   ```

5. **Reduce logging verbosity**:
   ```bash theme={null}
   # Change LOG_LEVEL from debug to info
   docker compose restart web-api
   ```

### High Database Connection Usage

**Problem**: Too many database connections consuming resources

**Solutions**:

1. **Monitor connections**:

   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   SELECT datname, count(*) FROM pg_stat_activity GROUP BY datname;
   ```

2. **Increase connection limit**:

   ```env theme={null}
   POSTGRES__MAX_OPEN_CONNECTION=20
   POSTGRES__MAX_IDEAL_CONNECTION=10
   ```

3. **Kill idle connections**:
   ```bash theme={null}
   psql -h localhost -U rapida_user -d web_db
   SELECT pg_terminate_backend(pid) FROM pg_stat_activity
   WHERE state = 'idle' AND query_start < now() - interval '1 hour';
   ```

### Slow Search/Analytics

**Problem**: OpenSearch searches timing out or slow

**Solutions**:

1. **Check OpenSearch status**:

   ```bash theme={null}
   curl http://localhost:9200/_cluster/health
   ```

2. **Monitor task queue**:

   ```bash theme={null}
   curl http://localhost:9200/_tasks?detailed
   ```

3. **Optimize index settings**:

   ```bash theme={null}
   # Reduce refresh frequency
   curl -X PUT "localhost:9200/assistant-conversations/_settings" \
     -H 'Content-Type: application/json' \
     -d '{"settings": {"refresh_interval": "30s"}}'
   ```

4. **Delete old indices**:
   ```bash theme={null}
   # Remove indices older than 30 days
   curl -X DELETE "localhost:9200/logs-2024-01-*"
   ```

## Debugging

### Enable Debug Logging

```bash theme={null}
# Update .env file
LOG_LEVEL=debug

# Restart service
docker compose restart web-api

# Monitor logs
docker logs -f web-api
```

### Check Service Configuration

```bash theme={null}
# Verify service has correct config
docker exec web-api env | grep POSTGRES
docker exec web-api env | grep REDIS

# Check if service can reach dependencies
docker exec web-api curl http://postgres:5432 2>&1
docker exec web-api curl http://redis:6379 2>&1
```

### View Network Details

```bash theme={null}
# List all networks
docker network ls

# Inspect api-network
docker network inspect api-network

# View network traffic (if netcat installed)
docker exec web-api netcat -zv redis 6379
```

### Health Checks

```bash theme={null}
# Readiness check (service ready to accept traffic)
curl -s http://localhost:9001/readiness/ | jq .

# Liveness check
curl -s http://localhost:9001/healthz/ | jq .
```

## Getting Help

### Collect Debug Information

```bash theme={null}
# System info
uname -a
docker --version
docker compose version

# Service status
docker ps -a
docker network ls

# Recent logs
docker logs web-api --tail=50 > web-api.log
docker logs postgres --tail=50 > postgres.log
docker logs redis --tail=50 > redis.log

# Resource usage
docker stats --no-stream > stats.log

# Configuration
cat env/.web.env > config-web.log
```

### Report Issues

When reporting an issue, include:

1. Steps to reproduce
2. Error message/logs
3. System information
4. What you tried to fix it
5. Output of debug commands above

### Contact Support

* **GitHub Issues**: [https://github.com/rapidaai/voice-ai/issues](https://github.com/rapidaai/voice-ai/issues)
* **Documentation**: [https://rapida.ai/docs](https://rapida.ai/docs)
* **Community**: [https://github.com/rapidaai/voice-ai/discussions](https://github.com/rapidaai/voice-ai/discussions)
* **Email**: [prashant@rapida.ai](mailto:prashant@rapida.ai)

## Quick Reference

### Common Commands

```bash theme={null}
# Status
make ps-all
docker ps

# Logs
make logs-all
docker logs -f web-api

# Restart services
make restart-all
docker compose restart

# Clean up
make clean
docker compose down -v

# Database
make shell-db
psql -h localhost -U rapida_user -d web_db

# Redis
redis-cli -h localhost -p 6379

# Verify services
curl http://localhost:9001/readiness/
```

## Next Steps

1. [Installation](/opensource/installation) - Installation guide
2. [Configuration](/opensource/configuration) - Config-related issues


# Phone Call Deployment
Source: https://doc.rapida.ai/voice-deployment-options/phone

Deploy your AI assistant on inbound and outbound phone calls with full telephony, STT, and TTS configuration.

The Phone Call deployment connects your assistant to the telephone network. Callers interact with your assistant through natural voice conversations over PSTN, SIP, or WebRTC — powered by your choice of telephony provider, speech-to-text engine, and text-to-speech voice.

<Info>
  Phone deployments require a telephony provider (Twilio, Vonage, Exotel, Asterisk, or SIP) with valid credentials configured in your [credential vault](/credential/rapida-credentials).
</Info>

<Tip>
  Use [Listen](/assistants/configuration/listen) and [Speak](/assistants/configuration/speak) to choose STT, TTS, VAD, noise cancellation, EOS, pronunciation, and latency settings before going live.
</Tip>

## Deployment channels

| Channel   | Direction          | Protocol                      |
| --------- | ------------------ | ----------------------------- |
| Twilio    | Inbound + Outbound | WebSocket media streams       |
| Vonage    | Inbound + Outbound | WebSocket audio streaming     |
| Exotel    | Inbound + Outbound | Cloud telephony (India & SEA) |
| Asterisk  | Inbound + Outbound | AudioSocket + WebSocket       |
| SIP Trunk | Inbound + Outbound | Direct SIP (RFC 3261)         |

## Creating a Phone Deployment

Navigate to your assistant, click **Configure Assistant**, then select **Deployments** from the sidebar. Click **Add Deployment** and choose **Phone Call**.

The phone deployment wizard walks you through four steps:

<Steps>
  <Step title="Telephony">
    Select and configure your telephony provider for inbound and outbound calls.

    **Required fields:**

    * **Provider** — Choose from Twilio, Vonage, Exotel, Asterisk, or SIP
    * **Credentials** — Select stored credentials from your vault for the chosen provider
    * **Phone Number** — The phone number associated with this deployment (for outbound caller ID and inbound routing)

    <Tip>
      Store your telephony credentials in the [credential vault](/credential/rapida-credentials) before creating the deployment. The wizard will let you select from your saved credentials.
    </Tip>
  </Step>

  <Step title="General Experience">
    Define how the assistant greets callers and handles session lifecycle.

    **Required fields:**

    * **Greeting** — The opening message spoken when a call connects. Supports `{{variable}}` syntax for dynamic content (e.g., `Hello {{name}}, how can I help you?`)

    **Advanced settings** (expand to configure):

    * **Error Message** — Fallback message spoken when an unexpected error occurs mid-call
    * **Unclear Speech Wait** — Seconds to wait after interrupted or unclear caller speech before asking the caller to repeat (0.5-5 seconds, default: 0.5s)
    * **Unclear Speech Message** — Message spoken when the caller interrupted but did not continue, or speech was not recognized confidently (default: `I didn't catch that. Could you repeat that?`)
    * **Idle Silence Timeout** — Duration of caller silence before Rapida prompts them (5-60 seconds, default: 30s)
    * **Idle Timeout Backoff** — How many times the idle timeout multiplies before ending the session (0-5, default: 2)
    * **Idle Message** — Message spoken when the caller hasn't responded (default: "Are you there?")
    * **Maximum Session Duration** — Hard limit before the call is automatically ended (180-600 seconds, default: 300s)
  </Step>

  <Step title="Voice Input (Speech-to-Text)">
    Configure how caller audio is transcribed into text for the LLM.

    **Required fields:**

    * **STT Provider** — Deepgram, AssemblyAI, Google, Azure, OpenAI Whisper, AWS Transcribe, Cartesia, Rev.ai, Speechmatics, Sarvam, Groq, or Nvidia
    * **Model** — Provider-specific model (e.g., Nova-3 for Deepgram)
    * **Language** — Primary transcription language
    * **Encoding** — Audio encoding format. Use **Mulaw** for Twilio, **PCM** for most other providers
    * **Sample Rate** — Audio sample rate (typically 8000 Hz for telephony)

    **Advanced settings** (expand to configure):

    **Voice Activity Detection (VAD)**

    * **VAD Provider** — Silero VAD (default) for detecting when the caller starts and stops speaking
    * **VAD Confidence** — Speech probability required for detection (default: 0.7). Higher values require more confident speech detection
    * **VAD Start/Stop Seconds** — Continuous speech/non-speech duration used to confirm speech boundaries (default: 0.2s each)

    **Background Noise Removal**

    * **Noise Cancellation Provider** — RNNoise (default). Removes background audio before transcription for improved accuracy

    **End of Speech (EOS) Detection**

    * **EOS Provider** — Silence-based EOS (default). Determines when the caller has finished their turn
    * **EOS Timeout** — Duration of silence that signals turn completion (default: 1000ms). Lower values make the assistant more responsive; higher values accommodate natural pauses

    <Note>
      The EOS timeout is the primary control for perceived latency. For IVR-style interactions, try 700ms. For conversational use cases where callers pause mid-thought, try 1200-1500ms.
    </Note>
  </Step>

  <Step title="Voice Output (Text-to-Speech)">
    Configure how assistant text responses are converted to speech audio.

    **Required fields:**

    * **TTS Provider** — ElevenLabs, Deepgram, Azure, Google, OpenAI, AWS Polly, Cartesia, Resemble, Rime, Sarvam, Neuphonic, MiniMax, Groq, Speechmatics, or Nvidia
    * **Model** — Provider-specific model (e.g., Sonic-2 for Cartesia)
    * **Language** — Output speech language
    * **Voice ID** — The specific voice to use from your TTS provider
    * **Encoding** — Audio encoding. Use **PCM Mulaw** for Twilio
    * **Sample Rate** — Output sample rate

    **Advanced settings** (expand to configure):

    **Pronunciation**

    * **Pronunciation Dictionaries** — Custom pronunciation rules for domain-specific terms, names, acronyms, and technical jargon

    **Conjunction Boundaries**

    * **Conjunction Boundaries** — Conjunctions treated as valid boundaries for adding natural pauses before delivering to the voice provider

    **Pause**

    * **Pause Duration** — Length of pause at conjunction boundaries (100-300ms, default: 240ms)

    Click **Deploy Phone** to save and activate the deployment.
  </Step>
</Steps>

## Configuring Inbound Calls

After deploying, you need to point your telephony provider's webhook to Rapida so incoming calls reach your assistant.

### Twilio

1. Log in to [Twilio Console](https://www.twilio.com/login)
2. Navigate to **Phone Numbers** > **Manage** > **Active numbers**
3. Select the phone number linked to this deployment
4. Under **Voice & Fax**, set **A CALL COMES IN** to **Webhook**
5. Enter the webhook URL:

```
https://assistant-01.rapida.ai/v1/talk/twilio/call/{ASSISTANT_ID}?x-api-key={RAPIDA_API_KEY}
```

6. Set the HTTP method to **POST** and click **Save**

<Tip>
  Find your Assistant ID on the assistant overview page or in the browser URL. Get your API key from the [credential vault](/credential/rapida-credentials).
</Tip>

### Vonage, Exotel, Asterisk, SIP

Each provider has a specific webhook format. See the integration guides:

* [Twilio Integration](/integrations/telephony/twilio)
* [Vonage Integration](/integrations/telephony/vonage)
* [Exotel Integration](/integrations/telephony/exotel)
* [Asterisk Integration](/integrations/telephony/asterisk)
* [SIP Integration](/integrations/telephony/sip)

## Triggering Outbound Calls

Use the Rapida SDK or REST API to programmatically initiate outbound calls:

<Note>
  Outbound call requests can override saved deployment settings for a single call through `CreatePhoneCallRequest.options`. Use this for per-recipient greetings, language, STT/TTS model, voice, model parameters, or AgentKit connection settings without editing the deployment.
</Note>

<CardGroup>
  <Card title="Create Call API" href="/api-reference/call/create-call">
    Trigger a single outbound call to a phone number with your assistant.
  </Card>

  <Card title="Bulk Call API" href="/api-reference/call/create-bulk-call">
    Launch outbound dialing campaigns to multiple numbers in parallel.
  </Card>
</CardGroup>

## Related

* [Create an Assistant](/assistants/create-assistant) — Set up your assistant before deploying
* [Listen](/assistants/configuration/listen) — Choose and tune STT, VAD, noise cancellation, and EOS settings
* [Speak](/assistants/configuration/speak) — Choose and tune TTS, voice, pronunciation, and speech delivery settings
* [Twilio Integration](/integrations/telephony/twilio) — Detailed Twilio setup guide
* [Conversation Logs](/activity/conversation-logs) — Monitor call transcripts and metrics
* [Webhooks](/assistants/webhook/overview) — Receive post-call events


# Web App / SDK Deployment
Source: https://doc.rapida.ai/voice-deployment-options/web-app

Integrate your AI assistant into any React application via the Rapida SDK or REST API.

The SDK / API deployment exposes your assistant through the Rapida React SDK and REST API. Unlike the Web Widget (which provides a pre-built UI), this deployment gives you full control over the user interface while Rapida handles the audio pipeline, LLM orchestration, and conversation state behind the scenes.

<Info>
  Voice capabilities (microphone input and spoken responses) are optional. You can build a text-only integration by skipping the Voice Input and Voice Output steps during configuration.
</Info>

<Tip>
  Use [Listen](/assistants/configuration/listen) when enabling microphone input and [Speak](/assistants/configuration/speak) when enabling spoken responses in your app.
</Tip>

## Creating an SDK / API Deployment

Navigate to your assistant, click **Configure Assistant**, then select **Deployments** from the sidebar. Click **Add Deployment** and choose **SDK / API**.

The SDK deployment wizard walks you through three steps:

<Steps>
  <Step title="General Experience">
    Define how the assistant greets users and handles session lifecycle.

    **Required fields:**

    * **Greeting** — Opening message sent when a session starts. Supports `{{variable}}` syntax for dynamic content passed as query parameters

    **Advanced settings** (expand to configure):

    * **Error Message** — Fallback message sent when an unexpected error occurs
    * **Unclear Speech Wait** — Seconds to wait after interrupted or unclear speech before asking the user to repeat (0.5-5 seconds, default: 0.5s)
    * **Unclear Speech Message** — Message sent when the user interrupted but did not continue, or speech was not recognized confidently (default: `I didn't catch that. Could you repeat that?`)
    * **Idle Silence Timeout** — Duration of user silence before Rapida sends a prompt (5-60 seconds, default: 30s)
    * **Idle Timeout Backoff** — How many times the idle timeout multiplies before ending the session (0-5, default: 2)
    * **Idle Message** — Message sent when the user hasn't responded (default: "Are you there?")
    * **Maximum Session Duration** — Hard limit before the session is automatically ended (180-600 seconds, default: 300s)
  </Step>

  <Step title="Voice Input (Speech-to-Text) — Optional">
    Enable microphone-based voice input. When configured, the SDK streams browser audio to Rapida for real-time transcription.

    **If enabled:**

    * **STT Provider** — Deepgram, AssemblyAI, Google, Azure, OpenAI Whisper, AWS Transcribe, Cartesia, Rev.ai, Speechmatics, Sarvam, Groq, or Nvidia
    * **Model** — Provider-specific transcription model
    * **Language** — Primary transcription language
    * **Encoding** — Audio encoding format
    * **Sample Rate** — Audio sample rate

    **Advanced settings** (expand to configure):

    * **Voice Activity Detection (VAD)** — Silero VAD with configurable confidence and start/stop seconds
    * **Background Noise Removal** — RNNoise for ambient noise removal
    * **End of Speech Detection** — Silence-based EOS with configurable timeout (default: 1000ms)

    <Tip>
      Click **Skip** to deploy without voice input. Your app can still send text messages via the SDK. You can enable voice input later by editing the deployment.
    </Tip>
  </Step>

  <Step title="Voice Output (Text-to-Speech) — Optional">
    Enable spoken audio responses. When configured, the SDK receives audio streams from Rapida and plays them through the browser.

    **If enabled:**

    * **TTS Provider** — ElevenLabs, Deepgram, Azure, Google, OpenAI, AWS Polly, Cartesia, Resemble, Rime, Sarvam, Neuphonic, MiniMax, Groq, Speechmatics, or Nvidia
    * **Model** — Provider-specific voice model
    * **Language** — Output speech language
    * **Voice ID** — The specific voice from your TTS provider

    **Advanced settings** (expand to configure):

    * **Pronunciation Dictionaries** — Custom pronunciation for domain-specific terms
    * **Conjunction Boundaries** — Natural pause points for more human-like speech
    * **Pause Duration** — Length of pause at conjunction boundaries (100-300ms, default: 240ms)

    Click **Deploy API** to save and activate the deployment. Click **Skip** to deploy without voice output.
  </Step>
</Steps>

## Integration Methods

After deployment, you can integrate via the React SDK or a public URL.

### React SDK

Install the Rapida React SDK:

```bash theme={null}
npm install @rapidaai/react
# or
yarn add @rapidaai/react
```

The SDK provides hooks and components for managing sessions, streaming audio, and receiving transcripts. Audio streams over WebRTC directly between the browser and Rapida — no relay servers or iframes required.

### Public URL

Every SDK / API deployment generates a public URL you can share or embed in an iframe:

```
https://app.rapida.ai/preview/public/assistant/{ASSISTANT_ID}?token={PROJECT_CREDENTIAL_KEY}
```

Pass agent arguments as query parameters:

```
?token={KEY}&name=John&account_id=12345
```

These variables are available in your assistant's greeting and prompt via the `{{variable}}` syntax.

## Input and Output Modes

| Voice Input | Voice Output | Integration Style                                  |
| ----------- | ------------ | -------------------------------------------------- |
| Disabled    | Disabled     | Text-only chat via SDK                             |
| Enabled     | Disabled     | Users speak, assistant replies with text           |
| Disabled    | Enabled      | Users type, assistant replies with voice + text    |
| Enabled     | Enabled      | Full voice conversation with real-time transcripts |

## Use Cases

<CardGroup>
  <Card title="Custom Voice Interface">
    Build a fully branded voice experience inside your own React application with complete UI control.
  </Card>

  <Card title="In-App Support">
    Add voice-powered support directly inside your SaaS product without redirecting users.
  </Card>

  <Card title="Voice Search">
    Implement voice-activated search for content-rich applications.
  </Card>

  <Card title="Accessibility">
    Enhance web accessibility with voice navigation for visually impaired users.
  </Card>
</CardGroup>

## Related

* [Create an Assistant](/assistants/create-assistant) — Set up your assistant before deploying
* [Listen](/assistants/configuration/listen) — Choose and tune STT, VAD, noise cancellation, and EOS settings
* [Speak](/assistants/configuration/speak) — Choose and tune TTS, voice, pronunciation, and speech delivery settings
* [Web Widget](/voice-deployment-options/web-widget) — Pre-built embeddable widget (no custom UI needed)
* [API Reference](/api-reference/installation) — SDK installation and authentication
* [Conversation Logs](/activity/conversation-logs) — Monitor sessions and transcripts


# Web Widget Deployment
Source: https://doc.rapida.ai/voice-deployment-options/web-widget

Embed an AI voice and chat widget on any website with a single script tag.

The Web Widget deployment embeds an interactive AI assistant directly into your website. Visitors can type messages, speak via microphone, and hear voice responses — all from a floating widget that loads with a single script tag. Voice input and output are optional; the widget works as a text-only chat by default.

<Info>
  Voice capabilities (microphone input and spoken responses) are optional. You can deploy a text-only chat widget by skipping the Voice Input and Voice Output steps during configuration.
</Info>

<Tip>
  Use [Listen](/assistants/configuration/listen) when enabling microphone input and [Speak](/assistants/configuration/speak) when enabling spoken responses for the widget.
</Tip>

## Creating a Web Widget Deployment

Navigate to your assistant, click **Configure Assistant**, then select **Deployments** from the sidebar. Click **Add Deployment** and choose **Web Widget**.

The web widget wizard walks you through four steps:

<Steps>
  <Step title="Experience">
    Define the greeting, quickstart questions, and session behaviour.

    **Required fields:**

    * **Greeting** — Welcome message displayed when the widget opens. Describe your agent so users know how to interact with it

    **Quickstart Questions:**

    * **Quickstart Questions** — Pre-configured questions displayed as clickable buttons below the greeting. Users can tap one to start a conversation instantly, or type their own query

    **Advanced settings** (expand to configure):

    * **Error Message** — Message shown when an unexpected error occurs
    * **Unclear Speech Wait** — Seconds to wait after interrupted or unclear speech before asking the user to repeat (0.5-5 seconds, default: 0.5s)
    * **Unclear Speech Message** — Message shown/spoken when the user interrupted but did not continue, or speech was not recognized confidently (default: `I didn't catch that. Could you repeat that?`)
    * **Idle Silence Timeout** — Duration of silence before Rapida prompts the user (5-60 seconds, default: 30s)
    * **Idle Timeout Backoff** — How many times the idle timeout multiplies before ending the session (0-5, default: 2)
    * **Idle Message** — Message spoken/shown when the user hasn't responded (default: "Are you there?")
    * **Maximum Session Duration** — Hard limit before the session is automatically ended (3-15 minutes, default: 5 min)
  </Step>

  <Step title="Voice Input (Speech-to-Text) — Optional">
    Enable microphone-based voice input for the widget. Users can speak instead of typing.

    **If enabled:**

    * **STT Provider** — Deepgram, AssemblyAI, Google, Azure, OpenAI Whisper, AWS Transcribe, Cartesia, Rev.ai, Speechmatics, Sarvam, Groq, or Nvidia
    * **Model** — Provider-specific transcription model
    * **Language** — Primary transcription language
    * **Encoding** — Audio encoding format
    * **Sample Rate** — Audio sample rate

    **Advanced settings** (expand to configure):

    * **Voice Activity Detection (VAD)** — Silero VAD with configurable confidence and start/stop seconds
    * **Background Noise Removal** — RNNoise for removing ambient noise before transcription
    * **End of Speech Detection** — Silence-based EOS with configurable timeout (default: 1000ms)

    <Tip>
      Click **Skip** to deploy a text-only widget without voice input. You can enable it later by editing the deployment.
    </Tip>
  </Step>

  <Step title="Voice Output (Text-to-Speech) — Optional">
    Enable spoken audio responses from the assistant. The assistant's text responses will be read aloud through the browser.

    **If enabled:**

    * **TTS Provider** — ElevenLabs, Deepgram, Azure, Google, OpenAI, AWS Polly, Cartesia, Resemble, Rime, Sarvam, Neuphonic, MiniMax, Groq, Speechmatics, or Nvidia
    * **Model** — Provider-specific voice model
    * **Language** — Output speech language
    * **Voice ID** — The specific voice from your TTS provider

    **Advanced settings** (expand to configure):

    * **Pronunciation Dictionaries** — Custom pronunciation for domain-specific terms, names, and acronyms
    * **Conjunction Boundaries** — Natural pause points at conjunctions for more human-like speech
    * **Pause Duration** — Length of pause at conjunction boundaries (100-300ms, default: 240ms)

    <Tip>
      Click **Skip** to deploy without voice output. Text responses will still appear in the chat. You can enable voice output later.
    </Tip>
  </Step>

  <Step title="Features">
    Enable additional content sections available in the web widget beyond the chat interface.

    **Available sections:**

    * **Help Center / Q\&A Listing** — Display a searchable FAQ section alongside the chat, powered by your knowledge base
    * **Product Catalog** — Show product listings and details within the widget
    * **Blog Post / Articles** — Surface blog posts and articles for self-service browsing

    Click **Deploy Web Widget** to save and activate the deployment.
  </Step>
</Steps>

## Embedding the Widget

After deployment, Rapida generates a pre-built widget script (`app.min.js`) hosted on the Rapida CDN. You configure it by setting `window.chatbotConfig` before the script loads.

### Quick Start

Add this to any page on your website:

```html theme={null}
<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

The default configuration renders a floating launcher in the bottom-right corner of the page. Clicking it opens the chat window with your assistant's greeting and quickstart questions.

<Note>
  Replace `YOUR_ASSISTANT_ID` with your assistant's ID (found on the assistant overview page) and `YOUR_PROJECT_CREDENTIAL_KEY` with your project credential key from the [credential vault](/credential/rapida-credentials).
</Note>

### Installation Options

Use the latest hosted widget script:

```html theme={null}
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

Pin to a specific widget build when you need controlled rollout:

```html theme={null}
<script defer src="https://cdn-01.rapida.ai/public/scripts/v1.2.0/app.min.js"></script>
```

You can also install the package from npm and serve the built `dist/app.min.js` file from your own application or CDN:

```bash theme={null}
npm install @rapidaai/web-widget
```

### Configuration Options

Set `window.chatbotConfig` before loading the widget script. The widget has two configuration layers:

* **Rapida layer** — connection, authentication, assistant version, user identity, language, and debug logging
* **UI layer** — native IBM AI Chat configuration exposed directly on `window.chatbotConfig`

Rapida always owns `messaging.customSendMessage` because text messages must go through the Rapida SDK. Rapida also appends its audio controls through `renderWriteableElements.afterInputElement`; if you provide your own `afterInputElement`, it is preserved and Rapida audio controls are appended after it.

Use the sectioned config shape below. Do not use a `carbon` config key.

```html theme={null}
<script>
  window.chatbotConfig = {
    // Required
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",

    // Optional: target a specific assistant version
    assistant_version: "VERSION_ID",

    // Optional: custom API base URL (for self-hosted deployments)
    api_base: "https://assistant-01.in.rapida.ai",

    // Optional: language for the widget UI (default: "en", auto-detects from <html lang="">)
    language: "en",

    // Optional: enable debug logging in the browser console
    debug: false,

    // Optional: user identification
    user: {
      name: "Jane Doe",
      user_id: "user-123",
      meta: {
        plan: "enterprise",
        source: "pricing-page",
      },
    },

    // Optional: assistant identity
    name: "Support Bot",
    logo_url: "https://example.com/avatar.png",

    // Optional: layout
    layout: {
      mode: "floating",          // "floating" | "docked-right" | "docked-left" | "inline"
      position: "bottom-right",  // "bottom-right" | "bottom-left" | "top-right" | "top-left"
      corners: "square",
      showFrame: true,
      customProperties: {
        width: "420px",
        height: "640px",
      },
    },

    // Optional: theme
    theme: {
      mode: "light",             // "light" | "dark" | "system"
      injectTheme: "g10",        // "white" | "g10" | "g90" | "g100"
    },

    // Optional: chat UI sections
    aiEnabled: false,
    header: {
      title: "Support Bot",
      showAiLabel: false,
      minimizeButtonIconType: "side-panel-right",
    },
    launcher: {
      isOn: true,
    },
    history: {
      isOn: false,
    },
    messaging: {
      messageTimeoutSecs: 150,
      messageLoadingIndicatorTimeoutSecs: 1,
    },
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

### Required Rapida Options

| Property       | Type     | Default  | Description                                                                         |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------- |
| `assistant_id` | `string` | required | Rapida assistant ID.                                                                |
| `token`        | `string` | required | Project credential key from the [credential vault](/credential/rapida-credentials). |

### Rapida Options

| Property            | Type                     | Default                             | Description                                                                        |
| ------------------- | ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------- |
| `api_base`          | `string`                 | `https://assistant-01.in.rapida.ai` | Rapida API base URL. Use this for self-hosted or environment-specific backends.    |
| `assistant_version` | `string`                 | latest version                      | Assistant version to load when the backend supports versioned deployments.         |
| `user.name`         | `string`                 | `Guest`                             | Display name for the current user.                                                 |
| `user.user_id`      | `string`                 | generated and stored locally        | Stable user ID. Provide one if your host app already has an authenticated user ID. |
| `user.meta`         | `Record<string, string>` | `{ source: "web plugin" }`          | Extra metadata sent to Rapida with the user session.                               |
| `language`          | `string`                 | host page language or `en`          | Locale passed to the UI. The widget also watches the `<html lang>` attribute.      |
| `debug`             | `boolean`                | `false`                             | Enables additional client logging and passes debug mode to the UI layer.           |
| `name`              | `string`                 | deployment name                     | Friendly assistant name. Used as the default `assistantName` and `header.title`.   |
| `logo_url`          | `string`                 | default assistant avatar            | Assistant avatar URL. Used as the default `assistantAvatarUrl`.                    |

### Theme Options

Use `theme` for all theme-level options.

| Property            | Type                                  | Default                   | Description                                                                                                                                                                   |
| ------------------- | ------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme.mode`        | `"light" \| "dark" \| "system"`       | `"light"`                 | Widget color mode. `dark` defaults the UI token injection to `g100`; `light` defaults it to `g10`; `system` lets the host or system decide unless `theme.injectTheme` is set. |
| `theme.injectTheme` | `"white" \| "g10" \| "g90" \| "g100"` | derived from `theme.mode` | UI theme token injected into the chat shadow DOM. Set this when the host page does not already provide compatible theme tokens.                                               |
| `theme.color`       | `string`                              | none                      | Legacy primary brand color. Prefer `layout.customProperties` for current UI customization.                                                                                    |

### Layout Options

`layout` can be a string for old embeds or an object for the current sectioned config.

```js theme={null}
window.chatbotConfig = {
  layout: {
    mode: "floating",
    position: "bottom-right",
    corners: "square",
    showFrame: true,
    customProperties: {
      width: "420px",
      height: "640px",
    },
  },
};
```

| Property                    | Type                                                           | Default                | Description                                                                                                    |
| --------------------------- | -------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `layout`                    | `string \| object`                                             | `"floating"`           | Widget layout. String values are still supported: `"floating"`, `"docked-right"`, `"docked-left"`, `"inline"`. |
| `layout.mode`               | `"floating" \| "docked-right" \| "docked-left" \| "inline"`    | `"floating"`           | Rapida placement mode.                                                                                         |
| `layout.position`           | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"`       | Floating launcher and panel position.                                                                          |
| `layout.showLauncher`       | `boolean`                                                      | `true` for floating    | Legacy launcher shortcut inside `layout`. Prefer `launcher.isOn`.                                              |
| `layout.showFrame`          | `boolean`                                                      | `true`                 | Keeps the native border and shadow frame.                                                                      |
| `layout.hasContentMaxWidth` | `boolean`                                                      | UI default             | Constrains message content to the UI max width.                                                                |
| `layout.corners`            | `"round" \| "square" \| object`                                | `"square"`             | Corner style. Use a string for all corners or an object for per-corner control.                                |
| `layout.customProperties`   | `Record<string, string>`                                       | generated for floating | CSS variable overrides for the chat UI. Values are raw CSS strings.                                            |

Per-corner `layout.corners` object:

| Property     | Type                  | Description                              |
| ------------ | --------------------- | ---------------------------------------- |
| `startStart` | `"round" \| "square"` | Top-left in LTR, top-right in RTL.       |
| `startEnd`   | `"round" \| "square"` | Top-right in LTR, top-left in RTL.       |
| `endStart`   | `"round" \| "square"` | Bottom-left in LTR, bottom-right in RTL. |
| `endEnd`     | `"round" \| "square"` | Bottom-right in LTR, bottom-left in RTL. |

Supported `layout.customProperties` keys:

| Key                                                 | Description                                   |
| --------------------------------------------------- | --------------------------------------------- |
| `height`                                            | Floating chat height.                         |
| `max-height`                                        | Floating chat maximum height.                 |
| `width`                                             | Floating chat width.                          |
| `min-height`                                        | Floating chat minimum height.                 |
| `max-width`                                         | Floating chat maximum width.                  |
| `z-index`                                           | Floating chat z-index.                        |
| `bottom-position`                                   | Floating panel distance from viewport bottom. |
| `right-position`                                    | Floating panel distance from viewport right.  |
| `top-position`                                      | Floating panel distance from viewport top.    |
| `left-position`                                     | Floating panel distance from viewport left.   |
| `launcher-default-size`                             | Launcher button size.                         |
| `launcher-position-bottom`                          | Launcher distance from viewport bottom.       |
| `launcher-position-right`                           | Launcher distance from viewport right.        |
| `launcher-extended-width`                           | Expanded launcher width.                      |
| `messages-max-width`                                | Maximum width for message content.            |
| `messages-min-width`                                | Minimum width for message content.            |
| `workspace-min-width`                               | Minimum width for workspace panels.           |
| `card-max-width`                                    | Maximum width for card responses.             |
| `launcher-color-background`                         | Launcher background color.                    |
| `launcher-color-avatar`                             | Launcher icon/avatar color.                   |
| `launcher-color-background-hover`                   | Launcher hover background.                    |
| `launcher-color-background-active`                  | Launcher active background.                   |
| `launcher-color-focus-border`                       | Launcher focus border color.                  |
| `launcher-mobile-color-text`                        | Mobile launcher text color.                   |
| `launcher-expanded-message-color-text`              | Expanded launcher text color.                 |
| `launcher-expanded-message-color-background`        | Expanded launcher background.                 |
| `launcher-expanded-message-color-background-hover`  | Expanded launcher hover background.           |
| `launcher-expanded-message-color-background-active` | Expanded launcher active background.          |
| `launcher-expanded-message-color-focus-border`      | Expanded launcher focus border color.         |
| `unread-indicator-color-background`                 | Unread indicator background color.            |
| `unread-indicator-color-text`                       | Unread indicator text color.                  |

### Header Options

| Property                           | Type                                                                                    | Default                            | Description                                                                                                         |
| ---------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `header.isOn`                      | `boolean`                                                                               | `true`                             | Enables the native chat header. Set `false` for a fully embedded or fullscreen experience with your own app header. |
| `header.title`                     | `string`                                                                                | `name` or deployment name          | Header title. Set `""` to remove the visible title.                                                                 |
| `header.name`                      | `string`                                                                                | UI default                         | Secondary name shown after the title. Set `""` to remove it.                                                        |
| `header.minimizeButtonIconType`    | `"close" \| "minimize" \| "side-panel-left" \| "side-panel-right" \| "side-panel-down"` | side-panel icon based on dock side | Icon for the close/minimize button.                                                                                 |
| `header.hideMinimizeButton`        | `boolean`                                                                               | `false`                            | Hides the close/minimize button.                                                                                    |
| `header.showRestartButton`         | `boolean`                                                                               | `false`                            | Shows the restart conversation button.                                                                              |
| `header.menuOptions`               | `Array<{ text: string }>`                                                               | none                               | Custom menu options in the header menu.                                                                             |
| `header.showAiLabel`               | `boolean`                                                                               | `false`                            | Shows the AI label in the header. Disabled by default.                                                              |
| `header.hideDefaultAiLabelContent` | `boolean`                                                                               | `true`                             | Hides the default AI label popover content.                                                                         |
| `header.hasContentMaxWidth`        | `boolean`                                                                               | `false`                            | Constrains the header to the message content width.                                                                 |
| `header.actions`                   | `ToolbarAction[]`                                                                       | none                               | Custom header toolbar actions.                                                                                      |

### Launcher Options

| Property                             | Type      | Default                                        | Description                                             |
| ------------------------------------ | --------- | ---------------------------------------------- | ------------------------------------------------------- |
| `launcher.isOn`                      | `boolean` | `true` for floating, `false` for docked/inline | Shows the floating launcher button.                     |
| `launcher.showUnreadIndicator`       | `boolean` | UI default                                     | Shows the unread dot on the launcher.                   |
| `launcher.mobile.avatarUrlOverride`  | `string`  | none                                           | Custom mobile launcher avatar or icon URL.              |
| `launcher.mobile.isOn`               | `boolean` | `false`                                        | Deprecated expanded call-to-action launcher state.      |
| `launcher.mobile.title`              | `string`  | translated default                             | Deprecated expanded launcher title.                     |
| `launcher.mobile.timeToExpand`       | `number`  | `15`                                           | Deprecated delay before launcher expansion, in seconds. |
| `launcher.desktop.avatarUrlOverride` | `string`  | none                                           | Custom desktop launcher avatar or icon URL.             |
| `launcher.desktop.isOn`              | `boolean` | `false`                                        | Deprecated expanded call-to-action launcher state.      |
| `launcher.desktop.title`             | `string`  | translated default                             | Deprecated expanded launcher title.                     |
| `launcher.desktop.timeToExpand`      | `number`  | `15`                                           | Deprecated delay before launcher expansion, in seconds. |

### Messaging Options

| Property                                       | Type      | Default       | Description                                                                                              |
| ---------------------------------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------- |
| `messaging.skipWelcome`                        | `boolean` | UI default    | Starts new conversations without requesting a welcome message.                                           |
| `messaging.messageTimeoutSecs`                 | `number`  | `150`         | Message timeout in seconds. Use `0` to disable automatic timeout.                                        |
| `messaging.messageLoadingIndicatorTimeoutSecs` | `number`  | `1`           | Delay before the UI shows a loading indicator. Use `0` to prevent the UI from showing one automatically. |
| `messaging.customSendMessage`                  | function  | Rapida bridge | Reserved. Rapida overwrites this so text is sent through the Rapida SDK.                                 |
| `messaging.customLoadHistory`                  | function  | none          | Optional function that returns native history items for the UI.                                          |
| `messaging.showStopButtonImmediately`          | `boolean` | `false`       | Shows the stop button as soon as a message request starts.                                               |

### Other UI Options

| Property                                 | Type                                             | Default                                        | Description                                                                                        |
| ---------------------------------------- | ------------------------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `history.isOn`                           | `boolean`                                        | `false`                                        | Enables the native history panel.                                                                  |
| `history.showMobileMenu`                 | `boolean`                                        | `true`                                         | Shows mobile header menu options for new chat and view chats.                                      |
| `history.startClosed`                    | `boolean`                                        | `false`                                        | Starts history closed and preserves open/closed state across responsive mode changes.              |
| `input.maxInputCharacters`               | `number`                                         | `10000`                                        | Maximum characters allowed in the text input.                                                      |
| `input.isVisible`                        | `boolean`                                        | `true`                                         | Shows or hides the main input surface.                                                             |
| `input.isDisabled`                       | `boolean`                                        | `false`                                        | Disables text input. Rapida also disables text input while audio mode is active.                   |
| `homescreen.isOn`                        | `boolean`                                        | `false`                                        | Enables the native home screen before chat.                                                        |
| `homescreen.greeting`                    | `string`                                         | none                                           | Greeting text on the home screen.                                                                  |
| `homescreen.starters.isOn`               | `boolean`                                        | UI default                                     | Shows starter buttons.                                                                             |
| `homescreen.starters.buttons`            | `Array<{ label: string; isSelected?: boolean }>` | none                                           | Starter utterances displayed as buttons.                                                           |
| `homescreen.customContentOnly`           | `boolean`                                        | `false`                                        | Hides the built-in greeting and starters so custom content can own the home screen.                |
| `homescreen.disableReturn`               | `boolean`                                        | `false`                                        | Prevents returning to the home screen after a user has sent a message.                             |
| `disclaimer.isOn`                        | `boolean`                                        | `false`                                        | Shows a disclaimer screen before chat.                                                             |
| `disclaimer.disclaimerHTML`              | `string`                                         | required when enabled                          | HTML content for the disclaimer. If this changes after acceptance, the user must accept again.     |
| `aiEnabled`                              | `boolean`                                        | `false`                                        | Enables AI visual styling. The widget disables this by default.                                    |
| `assistantName`                          | `string`                                         | `name` or deployment name                      | Assistant name used by the UI for accessibility, errors, and defaults.                             |
| `assistantAvatarUrl`                     | `string`                                         | `logo_url`                                     | Assistant avatar URL used by native messages.                                                      |
| `locale`                                 | `string`                                         | `language`                                     | UI locale. Prefer `language` unless you need to override only the UI.                              |
| `namespace`                              | `string`                                         | `rapida-chat`                                  | Namespace for DOM IDs, storage keys, and multi-instance isolation. Must be 30 characters or fewer. |
| `openChatByDefault`                      | `boolean`                                        | `true` for docked/inline, `false` for floating | Opens the chat when it first renders.                                                              |
| `shouldSanitizeHTML`                     | `boolean`                                        | `true`                                         | Sanitizes assistant HTML before rendering.                                                         |
| `shouldTakeFocusIfOpensAutomatically`    | `boolean`                                        | `false`                                        | Moves focus into the chat when it opens on page load.                                              |
| `disableCustomElementMobileEnhancements` | `boolean`                                        | `false`                                        | Disables mobile enhancements that can conflict with custom element embedding.                      |
| `isReadonly`                             | `boolean`                                        | `false`                                        | Puts the chat in read-only mode for viewing old conversations.                                     |
| `persistFeedback`                        | `boolean`                                        | `false`                                        | Keeps feedback controls visible beyond the latest message.                                         |
| `strings`                                | partial language pack                            | UI defaults                                    | Overrides built-in UI strings.                                                                     |
| `injectCarbonTheme`                      | `"white" \| "g10" \| "g90" \| "g100"`            | derived from `theme`                           | Raw UI prop. Prefer `theme.injectTheme`.                                                           |
| `onError`                                | function                                         | none                                           | Called for catastrophic UI errors.                                                                 |

### Upload Options

File upload is experimental in the underlying UI.

| Property                  | Type      | Default        | Description                                                                    |
| ------------------------- | --------- | -------------- | ------------------------------------------------------------------------------ |
| `upload.is_on`            | `boolean` | `false`        | Enables the attachment button. Requires `upload.onFileUpload`.                 |
| `upload.accept`           | `string`  | all file types | Accepted MIME types or extensions, same format as the HTML `accept` attribute. |
| `upload.maxFileSizeBytes` | `number`  | none           | Client-side maximum file size.                                                 |
| `upload.maxFiles`         | `number`  | none           | Maximum number of pending files.                                               |
| `upload.onFileUpload`     | function  | none           | Called once per selected file. Return structured data for the pending message. |

### Keyboard Shortcut Options

Keyboard shortcut configuration is experimental in the underlying UI.

| Property                                               | Type      | Default | Description                                      |
| ------------------------------------------------------ | --------- | ------- | ------------------------------------------------ |
| `keyboardShortcuts.messageFocusToggle.is_on`           | `boolean` | `true`  | Enables the message/input focus toggle shortcut. |
| `keyboardShortcuts.messageFocusToggle.key`             | `string`  | `"F6"`  | Primary shortcut key.                            |
| `keyboardShortcuts.messageFocusToggle.modifiers.alt`   | `boolean` | `false` | Requires Alt.                                    |
| `keyboardShortcuts.messageFocusToggle.modifiers.shift` | `boolean` | `false` | Requires Shift.                                  |
| `keyboardShortcuts.messageFocusToggle.modifiers.ctrl`  | `boolean` | `false` | Requires Control.                                |
| `keyboardShortcuts.messageFocusToggle.modifiers.meta`  | `boolean` | `false` | Requires Command/Meta.                           |

### Service Desk Options

These are advanced native UI options for human-agent handoff integrations.

| Property                                 | Type      | Default    | Description                                                                                         |
| ---------------------------------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `serviceDeskFactory`                     | function  | none       | Factory that creates a service desk integration instance.                                           |
| `serviceDesk.availabilityTimeoutSeconds` | `number`  | UI default | Timeout used while checking whether human agents are available.                                     |
| `serviceDesk.skipConnectHumanAgentCard`  | `boolean` | `false`    | Auto-connects to an available agent after a connect-to-agent response while still showing the card. |
| `serviceDesk.agentJoinTimeoutSeconds`    | `number`  | none       | Timeout while waiting for an agent to join after one is requested.                                  |
| `serviceDesk.allowReconnect`             | `boolean` | `true`     | Attempts to reconnect the user to a prior human-agent conversation when supported.                  |

### Render And Lifecycle Hooks

| Property                           | Type     | Description                                                                                                          |
| ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `onBeforeRender(instance)`         | function | Called before the UI renders. Rapida uses this internally, then calls your handler.                                  |
| `onAfterRender(instance)`          | function | Called after the UI renders.                                                                                         |
| `onViewPreChange(event, instance)` | function | Called before the chat opens or closes. Can return a promise to delay the view change.                               |
| `onViewChange(event, instance)`    | function | Called after the chat opens or closes. Rapida uses this to track docked/inline shell state, then calls your handler. |
| `renderUserDefinedResponse`        | function | Renders custom `user_defined` response items.                                                                        |
| `renderCustomMessageFooter`        | function | Renders custom message footers.                                                                                      |
| `renderWriteableElements`          | object   | Renders writable slots. Rapida merges `afterInputElement` with its audio controls.                                   |

### Layout Modes

#### Floating

A fixed-position panel with a launcher button. Click the launcher to open or close the chat.

```js theme={null}
window.chatbotConfig = {
  layout: {
    mode: "floating",
    position: "bottom-right",
  },
  launcher: {
    isOn: true,
  },
};
```

#### Docked

A side panel fixed to the viewport. When open, it pushes page content to make room.

```js theme={null}
window.chatbotConfig = {
  layout: {
    mode: "docked-right", // or "docked-left"
  },
};
```

#### Inline

The widget flows with the page content. Place the `<div id="rapida-chat-app">` where you want it to render.

```html theme={null}
<div id="rapida-chat-app"></div>
<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
    layout: {
      mode: "inline",
    },
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

### Legacy Shortcuts

These remain supported for old embeds. Prefer the sectioned config above for new usage.

| Property                 | Replacement                        |
| ------------------------ | ---------------------------------- |
| `layout: "floating"`     | `layout: { mode: "floating" }`     |
| `layout: "docked-right"` | `layout: { mode: "docked-right" }` |
| `layout: "docked-left"`  | `layout: { mode: "docked-left" }`  |
| `layout: "inline"`       | `layout: { mode: "inline" }`       |
| `position`               | `layout.position`                  |
| `showLauncher`           | `launcher.isOn`                    |

### Full HTML Example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>

  <!-- Rapida Web Widget Configuration -->
  <script>
    window.chatbotConfig = {
      assistant_id: "YOUR_ASSISTANT_ID",
      token: "YOUR_PROJECT_CREDENTIAL_KEY",
      user: {
        name: "Jane Doe",
        user_id: "website-visitor-001",
        meta: {
          source: "marketing-site",
          page: window.location.pathname,
        },
      },
      name: "Support Bot",
      logo_url: "https://example.com/avatar.png",
      layout: {
        mode: "floating",
        position: "bottom-right",
        customProperties: {
          width: "420px",
          height: "640px",
        },
      },
      theme: {
        mode: "light",
        injectTheme: "g10",
      },
      header: {
        title: "Support Bot",
        showAiLabel: false,
      },
      launcher: {
        isOn: true,
      },
    };
  </script>
  <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
</body>
</html>
```

<Tip>
  Place both script tags just before the closing `</body>` tag. The `defer` attribute on `app.min.js` ensures it loads after the config is set without blocking page rendering.
</Tip>

### Full-Screen Widget

To make the widget fill the entire viewport, use `inline` mode and mount the widget into a full-page `#rapida-chat-app` element:

```html theme={null}
<style>
  html,
  body,
  #rapida-chat-app {
    width: 100%;
    height: 100%;
    margin: 0;
  }
</style>
<div id="rapida-chat-app"></div>
<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
    layout: {
      mode: "inline",
      showFrame: false,
    },
    header: {
      isOn: false,
    },
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

## Platform Integration Guides

<AccordionGroup>
  <Accordion title="WordPress">
    1. Go to **Appearance** > **Theme File Editor** (or use a plugin like **Insert Headers and Footers**)
    2. Add the following before the closing `</body>` tag in your theme's `footer.php`:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```

    3. Save and verify the widget loads on your site
  </Accordion>

  <Accordion title="Shopify">
    1. Go to **Online Store** > **Themes** > **Edit Code**
    2. Open `theme.liquid`
    3. Add the scripts before the closing `</body>` tag:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```

    4. Save and preview your store
  </Accordion>

  <Accordion title="Webflow">
    1. Go to **Project Settings** > **Custom Code**
    2. Paste in the **Footer Code** section:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```

    3. Publish your site
  </Accordion>

  <Accordion title="Squarespace">
    1. Go to **Settings** > **Advanced** > **Code Injection**
    2. Paste in the **Footer** section:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```

    3. Save and preview your site
  </Accordion>

  <Accordion title="Next.js">
    Use Next.js `Script` component in your root layout:

    ```tsx theme={null}
    // app/layout.tsx (App Router)
    import Script from "next/script";

    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script id="rapida-config" strategy="beforeInteractive">
              {`window.chatbotConfig = {
                assistant_id: "${process.env.NEXT_PUBLIC_RAPIDA_ASSISTANT_ID}",
                token: "${process.env.NEXT_PUBLIC_RAPIDA_TOKEN}",
              };`}
            </Script>
            <Script
              src="https://cdn-01.rapida.ai/public/scripts/app.min.js"
              strategy="lazyOnload"
            />
          </body>
        </html>
      );
    }
    ```
  </Accordion>

  <Accordion title="Vue / Nuxt">
    ```ts theme={null}
    // nuxt.config.ts
    export default defineNuxtConfig({
      app: {
        head: {
          script: [
            {
              children: `window.chatbotConfig = {
                assistant_id: "YOUR_ASSISTANT_ID",
                token: "YOUR_PROJECT_CREDENTIAL_KEY",
              };`,
            },
            {
              src: "https://cdn-01.rapida.ai/public/scripts/app.min.js",
              defer: true,
            },
          ],
        },
      },
    });
    ```

    For plain Vue, add the script tags directly to `public/index.html`.
  </Accordion>

  <Accordion title="Angular">
    Add to `src/index.html` before the closing `</body>` tag:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```
  </Accordion>

  <Accordion title="Static HTML / Any Website">
    Copy and paste the following into any HTML page:

    ```html theme={null}
    <script>
      window.chatbotConfig = {
        assistant_id: "YOUR_ASSISTANT_ID",
        token: "YOUR_PROJECT_CREDENTIAL_KEY",
      };
    </script>
    <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
    ```
  </Accordion>
</AccordionGroup>

## Self-Hosted Deployment

If you're running Rapida on your own infrastructure, override the `api_base` to point at your assistant API:

```html theme={null}
<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
    api_base: "https://your-assistant-api.example.com",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
```

You can also self-host the widget script itself. Build the `react-widget` SDK and upload the generated `dist/app.min.js` to your own CDN or static file server:

```bash theme={null}
cd sdks/react-widget
npm install
npm run build
# Upload dist/app.min.js to your CDN
```

Then reference your self-hosted script:

```html theme={null}
<script defer src="https://your-cdn.example.com/scripts/app.min.js"></script>
```

## How It Works

When the widget script loads, it:

1. Reads configuration from `window.chatbotConfig`
2. Reuses an existing `<div id="rapida-chat-app">` or creates one and appends it to the page `<body>`
3. Initialises a `VoiceAgent` instance using the `@rapidaai/react` SDK with the web plugin client connection
4. Fetches the assistant's web plugin deployment config (greeting, suggestions, voice settings)
5. Renders the configured layout: floating launcher, docked side panel, or inline chat
6. Supports both text input and voice input (with microphone visualizer, device selection, and mute controls)
7. Passes supported UI configuration through to the native IBM AI Chat layer
8. Auto-detects language changes on the `<html lang="">` attribute
9. Persists the user ID in `localStorage` (`rpd__uuid`) across sessions when no `user.user_id` is provided

## Widget Features

The pre-built widget includes:

* **Text chat** — Type messages and receive markdown-rendered responses
* **Voice input** — Click the audio icon to switch to voice mode with real-time microphone visualization
* **Microphone device selector** — Choose from available input devices via a dropdown flyout
* **Mute/unmute** — Toggle microphone during voice conversations
* **Quickstart suggestions** — Clickable buttons from your deployment's configured suggestions
* **Session reset** — Restart the conversation via the header button
* **Auto-scroll** — Chat automatically scrolls to the latest message
* **Layout modes** — Use floating, docked-right, docked-left, or inline rendering
* **Theme controls** — Use light, dark, system, or explicit UI token injection

## Input and Output Modes

| Voice Input | Voice Output | User Experience                                 |
| ----------- | ------------ | ----------------------------------------------- |
| Disabled    | Disabled     | Text-only chat                                  |
| Enabled     | Disabled     | Users speak, assistant replies with text        |
| Disabled    | Enabled      | Users type, assistant replies with voice + text |
| Enabled     | Enabled      | Full voice conversation with text transcript    |

## Troubleshooting

| Issue                              | Solution                                                                                                                                                                                                    |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Widget does not appear             | Verify `assistant_id` and `token` are correct. Check the browser console for errors — the widget logs `"Please provide an assistant_id"` or `"Please provide an authentication token"` if either is missing |
| Voice input not working            | Ensure the page is served over HTTPS (required for microphone access). Check that the deployment has STT configured                                                                                         |
| Widget loads but shows no greeting | Ensure you have an active **Web Widget** deployment for this assistant (not an SDK/API deployment)                                                                                                          |
| User ID resets across visits       | The widget stores the auto-generated ID in `localStorage` as `rpd__uuid`. If `localStorage` is cleared, a new ID is generated. Pass a stable `user.user_id` in the config to avoid this                     |
| CORS errors in console             | If self-hosting, ensure your reverse proxy allows requests from your website's origin to the assistant API                                                                                                  |
| `window.chatbotConfig` not read    | Make sure the config script runs **before** `app.min.js`. Use a regular `<script>` tag (not `defer`) for the config, and `defer` on the widget script                                                       |

## Use Cases

<CardGroup>
  <Card title="Customer Support">
    Provide instant answers and reduce support ticket volume with 24/7 voice-enabled help.
  </Card>

  <Card title="Lead Generation">
    Engage visitors with qualifying questions and route them to your sales team.
  </Card>

  <Card title="Product Recommendations">
    Guide users through product catalogs with personalized suggestions.
  </Card>

  <Card title="Appointment Scheduling">
    Let users book appointments directly through conversational flow.
  </Card>
</CardGroup>

## Related

* [Create an Assistant](/assistants/create-assistant) — Set up your assistant before deploying
* [Listen](/assistants/configuration/listen) — Choose and tune STT, VAD, noise cancellation, and EOS settings
* [Speak](/assistants/configuration/speak) — Choose and tune TTS, voice, pronunciation, and speech delivery settings
* [Web App (React SDK)](/voice-deployment-options/web-app) — Full SDK integration for custom React apps with complete UI control
* [Credentials](/credential/rapida-credentials) — Manage your project credential keys
* [Conversation Logs](/activity/conversation-logs) — Monitor widget conversations
* [Webhooks](/assistants/webhook/overview) — Receive post-conversation events


# WhatsApp Deployment
Source: https://doc.rapida.ai/voice-deployment-options/whatsapp

Connect your AI assistant to WhatsApp Business for automated conversational interactions at scale.

The WhatsApp deployment connects your assistant to WhatsApp Business via the Meta Cloud API. Users interact with your assistant through text messages on the world's most widely used messaging platform. The assistant maintains full multi-turn conversation context across messages in the same thread.

<Info>
  WhatsApp deployments use the Meta WhatsApp Business API. You need a WhatsApp Business Account with an approved phone number and a Meta developer app before configuring this deployment.
</Info>

## Prerequisites

Before deploying to WhatsApp, ensure you have:

<CardGroup>
  <Card title="WhatsApp Business Account">
    A [WhatsApp Business Account](https://business.whatsapp.com/) with an approved phone number registered on the Meta Business platform.
  </Card>

  <Card title="Meta Developer App">
    A Meta developer account with a WhatsApp Business API app created in the [Meta Developer Portal](https://developers.facebook.com/).
  </Card>
</CardGroup>

You will need these credentials from your Meta developer portal:

* **Access Token** — Your WhatsApp Business API access token (permanent or temporary)
* **Phone Number ID** — The phone number ID for your WhatsApp Business number
* **Webhook Verify Token** — A secret string you define, used to verify Meta's webhook callback

## Creating a WhatsApp Deployment

<Steps>
  <Step title="Navigate to your assistant">
    Go to **Assistants** in the sidebar and select the assistant you want to deploy to WhatsApp.
  </Step>

  <Step title="Open deployment settings">
    Click **Configure Assistant**, then select **Deployments** from the left sidebar.
  </Step>

  <Step title="Add WhatsApp deployment">
    Click **Add Deployment** and choose **WhatsApp**.
  </Step>

  <Step title="Enter your WhatsApp credentials">
    Provide:

    * **Access Token** — Your Meta WhatsApp Business API access token
    * **Phone Number ID** — The phone number ID for your WhatsApp Business number
    * **Webhook Verify Token** — A secret string you define (you'll use this same string in the Meta webhook configuration)
  </Step>

  <Step title="Configure the conversation experience">
    Define how the assistant starts and handles the session.

    **Experience settings:**

    * **Greeting** — Opening message sent when a WhatsApp session starts
    * **Error Message** — Fallback message sent when an unexpected error occurs
    * **Unclear Input Timeout** — Seconds to wait after unclear input before asking the user to repeat (0.5-5 seconds, default: 0.5s)
    * **Unclear Input Message** — Message sent when the assistant could not understand the user's input (default: `I didn't catch that. Could you repeat that?`)
    * **Idle Silence Timeout** — Duration of user silence before Rapida sends a prompt (5-120 seconds, default: 30s)
    * **Idle Message** — Message sent when the user hasn't responded (default: "Are you there?")
  </Step>

  <Step title="Configure the Meta webhook">
    In the Meta developer portal, set your webhook URL to:

    ```
    https://api.rapida.ai/v1/whatsapp/event/{ASSISTANT_ID}
    ```

    Set the **Verify Token** to the same value you entered in Rapida.
  </Step>

  <Step title="Subscribe to message events">
    In the Meta webhook configuration, subscribe to the **messages** field under the WhatsApp Business Account product. This ensures Rapida receives incoming messages from your users.
  </Step>
</Steps>

## How It Works

When a user sends a WhatsApp message to your business number:

1. Meta delivers the message to Rapida via the configured webhook
2. Rapida routes the message to the correct assistant based on the Assistant ID in the webhook URL
3. The assistant processes the message through its configured LLM, tools, and knowledge bases
4. The response is sent back to the user via the WhatsApp Business API
5. Conversation context is maintained across all messages in the same thread

## Key Features

* **Multi-turn context** — The assistant maintains full conversation context across messages. Users can reference previous messages naturally
* **Messaging at scale** — Handle thousands of simultaneous WhatsApp conversations with a single assistant
* **Rich content** — Send and receive text messages, with support for structured responses
* **24/7 availability** — Automate responses around the clock without human intervention
* **Same brain, different channel** — The assistant uses the same prompt, model, tools, and knowledge bases as your phone and web deployments

## Use Cases

<CardGroup>
  <Card title="Customer Support">
    Automate first-line support for product inquiries, order status, and troubleshooting on the platform your customers already use.
  </Card>

  <Card title="Appointment Booking">
    Let users book, reschedule, or cancel appointments directly in WhatsApp with natural language.
  </Card>

  <Card title="Order Management">
    Handle order tracking, returns, and product availability queries conversationally.
  </Card>

  <Card title="Lead Qualification">
    Engage inbound leads with qualifying questions and route warm leads to your sales team.
  </Card>

  <Card title="Notifications and Reminders">
    Send proactive messages for appointment reminders, payment confirmations, and delivery alerts.
  </Card>

  <Card title="Surveys and Feedback">
    Collect customer feedback and NPS scores through conversational surveys that feel natural.
  </Card>
</CardGroup>

## Related

* [Create an Assistant](/assistants/create-assistant) — Set up your assistant before deploying
* [Phone Call Deployment](/voice-deployment-options/phone) — Deploy the same assistant on phone calls
* [Web Widget Deployment](/voice-deployment-options/web-widget) — Embed on your website
* [Webhooks](/assistants/webhook/overview) — Receive post-conversation events


# Create a project
Source: https://doc.rapida.ai/workspace/create-new-project

Learn how to create a new project in the Rapida platform

In Rapida, projects are the foundation for organizing your work. Creating a new project is a straightforward process that allows you to set up a dedicated space for your tasks, resources, and collaborations.

<img alt="Create a New Project" />

To create a new project:

1. Navigate to the project listing page.

2. Click on the "Create Project" or "+" button (exact wording may vary).

3. A dialog box will appear with the following fields:

   * **Project Name**: Enter a unique, descriptive name for your project.
     Example: "My Favorite Project"

   * **Project Description**: Provide a brief overview of what the project is about.
     This helps team members understand the project's purpose at a glance.

4. After filling in the required information, click the "Create Project" button.

## Best Practices for Project Creation

* Choose a clear, concise name that reflects the project's purpose.
* Write a description that gives a quick overview of the project's goals.
* Consider who will need access to the project and be prepared to add collaborators.

## Next Steps

After creating your project, you can:

* Add collaborators and set their permissions
* Create assistants specific to your project needs
* Set up knowledge bases relevant to your project
* Configure project-specific endpoints

Remember, each project in Rapida operates as its own ecosystem, allowing you to tailor resources and permissions to the specific needs of your work.


# Invite a User
Source: https://doc.rapida.ai/workspace/invite-a-user

Learn how to invite new users to your Rapida workspace

Inviting new users to your Rapida workspace is a simple process that allows you to expand your team and manage access to your projects. Follow these steps to invite a new user.

<Steps>
  <Step title="Access User Management">
    Navigate to the user management page in your Rapida workspace.
  </Step>

  <Step title="Initiate Invitation">
    Click on the "Create new user" or "Invite new user" button, typically located
    at the top right of the user listing.
  </Step>

  <Step title="Fill in User Details">
    In the "Invite new user" dialog that appears, provide the following information:

    <Frame>
      <img alt="Invite New User Dialog" />
    </Frame>

    * **Project Role**: Select the appropriate role from the dropdown (e.g., Super Admin, Admin, Writer, Reader).
    * **Email Address**: Enter the email address of the person you're inviting.
    * **Projects**: Choose which project(s) to give the new user access to.
  </Step>

  <Step title="Set Permissions">
    Depending on the selected role, you may need to specify additional permissions
    or access levels.

    <Frame>
      <img alt="Invite New User Dialog" />
    </Frame>
  </Step>

  <Step title="Send Invitation">
    After filling in all required fields, click the "Invite User" button to send the invitation.
  </Step>
</Steps>

## User Roles

When inviting a new user, you can assign one of the following roles:

* **Super Admin**: Full access and control over the organization and all its projects
* **Admin**: Manage organization resources and users
* **Writer**: Can edit and contribute to assigned projects
* **Reader**: Read-only access to permitted resources

## Important Considerations

* Ensure you're assigning the appropriate role for the new user's responsibilities.
* Double-check the email address to avoid sending invitations to the wrong person.
* Be mindful of which projects you're granting access to, especially for sensitive or confidential work.

## After Sending the Invitation

* The invited user will receive an email with instructions to join the workspace.
* They will need to create an account or log in if they already have one.
* Once they accept the invitation, they'll have access based on the role and projects you've assigned.

## Best Practices

* Regularly review and update user roles and project access as team responsibilities change.
* Implement a standard onboarding process for new users to familiarize them with your workspace setup and guidelines.
* Periodically audit user accounts to ensure all active users still require access.

By following these steps, you can efficiently manage your team's access to your Rapida workspace, ensuring smooth collaboration and appropriate security measures.


# Workspace Overview
Source: https://doc.rapida.ai/workspace/overview

A quick guide to navigating and managing your Rapida workspace

The Rapida workspace is your central hub for managing projects, users, and resources. This overview will help you understand how different components work together.

## Key Components

1. **Projects**: The core units of organization in Rapida.
2. **User Management**: Control access and roles across your organization.
3. **Collaboration**: Invite and manage team members within projects.

## Navigating Your Workspace

<img alt="Project Selection" />

* **Project Switching**: Use the dropdown menu to switch between projects you have access to.
* **Role Visibility**: Your role in each project is displayed, affecting your permissions.
* **User Interface**: The interface updates to show project-specific resources and options when you switch.

## Quick Links

* [Create a New Project](/workspace/create-new-project)
* [Manage Users](/workspace/user-management)
* [Invite Team Members](/workspace/invite-a-user)
* [Project Management](/workspace/project-management)

## Best Practices

* Regularly review project and user permissions
* Use clear, descriptive names for projects and users
* Implement a consistent onboarding process for new team members
* Periodically audit workspace usage and access

By leveraging these interconnected features, you can create a streamlined and secure environment for your team's collaborative efforts in Rapida.


# Project Management
Source: https://doc.rapida.ai/workspace/project-management

Understanding project structure and permissions in the Rapida platform

## Overview

In Rapida, projects are the cornerstone of organization. Each project serves as a container for various resources and activities. An organization can have multiple projects, each with its own set of permissions and collaborators.

<img alt="Project Listing" />

The project listing page displays all projects within your organization. Key elements include:

* **Name**: Unique identifier for each project
* **Date Created**: Project creation date
* **Your Role**: Your specific role within each project
* **Collaborators**: Visual representation of team members involved

## Project Structure

Each project in Rapida can contain:

1. **Assistants**: AI helpers tailored to project needs
2. **Logs**: Activity records specific to the project
3. **Endpoints**: Project-specific API endpoints
4. **Knowledge**: Dedicated information repositories

## Project Permissions

Permissions in Rapida are project-based, allowing for granular access control:

* **Super Admin**: Full access and control over the project
* **Admin**: Manage project resources and collaborators
* **Member**: Contribute to and use project resources
* **Viewer**: Read-only access to project data

### Key Points:

* Permissions are set at the project level, not organization-wide
* A user can have different roles in different projects
* Organization admins can manage projects but don't automatically have access to all project data

## Managing Multiple Projects

Organizations in Rapida can host multiple projects:

* Each project is isolated from others
* Resources and permissions don't overlap between projects
* Users can be part of multiple projects with varying roles

## Best Practices

* Clearly define project scopes to avoid overlap
* Regularly review and update project permissions
* Use descriptive project names for easy identification
* Leverage project-specific resources for targeted workflows

Remember, while your organization may have numerous projects, each project operates as its own ecosystem within the Rapida platform.


# User Management
Source: https://doc.rapida.ai/workspace/user-management

Understanding user roles and management in the Rapida platform

## Overview

In Rapida, effective user management is crucial for maintaining organization security and productivity. The platform allows you to manage users, their roles, and access levels across your organization.

<img alt="User Listing" />

The user management page displays all users within your organization. Key elements include:

* **User ID**: Unique identifier for each user
* **Name**: Display name of the user
* **Email**: User's email address
* **Role**: User's role within the organization
* **Joined On**: Date the user joined the organization
* **Status**: Current status of the user account

## User Roles

Rapida uses a role-based access control system:

* **Super Admin**: Full access and control over the organization and all its projects
* **Admin**: Manage organization resources and users
* **Member**: Standard user with access to assigned projects
* **Viewer**: Read-only access to permitted resources

### Key Points:

* Roles determine the level of access and permissions a user has
* All users shown in the image have the "Super Admin" role
* Roles can be assigned at the organization or project level

## Managing Users

The user management interface allows administrators to:

1. **Add New Users**: The "Create new user" button at the top right allows adding new members
2. **View User Details**: Each user entry provides essential information at a glance
3. **Edit User Information**: The ellipsis (...) at the end of each row likely provides options to edit user details
4. **Activate/Deactivate Users**: The "Status" column shows if a user is active or not

## User Statuses

Users can have different statuses:

* **Active**: User has full access according to their role
* **Inactive**: User account is disabled (not shown in the image, but a common option)

## Best Practices

* Regularly review user roles and permissions
* Promptly update access for users who change positions or leave the organization
* Use descriptive names and professional email addresses for user accounts
* Implement a process for periodically auditing user accounts and their activities