AI Chat Service RPC API

This API uses JSON-RPC 2.0 for communication between the client and server.

Base URL

http://localhost:8080

Authentication

All methods require project_id and token for authentication and customer identification.

General Request Format

{ "jsonrpc": "2.0", "method": "", "params": { "project_id": "", "token": "", // other method-specific parameters }, "id": "" }

General Response Format

{ "jsonrpc": "2.0", "result": { // method-specific result }, "id": "" }

Methods

1. create_conversation

Creates a new conversation or reinitializes an existing one.

Request

{ "jsonrpc": "2.0", "method": "create_conversation", "params": { "project_id": "", "token": "", "id": "", "config_url": "", "reinit": , "conversation_timeout": , "user_meta_data": { // user-specific metadata } }, "id": "" }

• id: String. Unique identifier for the conversation.
• config_url: String. URL to fetch the configuration for the conversation. This URL should return a JSON object with configuration settings.
• reinit: Boolean (optional). If true, reinitializes an existing conversation.
• conversation_timeout: Integer (optional). Timeout in seconds for conversation inactivity. Default is 3600 (60 minutes).
• user_meta_data: Object (optional). Additional metadata related to the user. This can include preferences, settings, or other contextual information. If post-processing is enabled, this data will be sent along with it.

Response

{ "jsonrpc": "2.0", "result": { "status": "", "id": "", "initial_message": "" }, "id": "" }

• status: String. Can be "created", "reinitialized", or "exists".
• id: String. The conversation ID.
• initial_message: String. The initial message from the AI (if a new conversation was created or reinitialized).

2. chat

Sends a message to an existing conversation and receives a response. If the conversation does not exist and a config_url is provided, a new conversation is created.

Request

{ "jsonrpc": "2.0", "method": "chat", "params": { "project_id": "", "token": "", "id": "", "message": "", "role": "", "config_url": "", // optional "user_meta_data": { // optional // user-specific metadata } }, "id": "" }

• id: String. The ID of the existing conversation.
• message: String. The user's message to send to the AI.
• role: String (optional). The role of the message sender. Can be "user" or "system". Default is "user".
• config_url: String (optional). URL to fetch the configuration for the conversation. If provided and the conversation does not exist, a new conversation will be created.
• user_meta_data: Object (optional). Additional metadata related to the user. This can include preferences, settings, or other contextual information. If post-processing is enabled, this data will be sent along with it when a new conversation is auto-created with a config_url.

Response

{ "jsonrpc": "2.0", "result": { "response": "" }, "id": "" }

• response: String. The AI's response to the user's message. If a new conversation was created, this will be the initial AI message.

3. delete

Deletes an existing conversation.

Request

{ "jsonrpc": "2.0", "method": "delete", "params": { "project_id": "", "token": "", "id": "" }, "id": "" }

• id: String. The ID of the conversation to delete.

Response

{ "jsonrpc": "2.0", "result": { "status": "", "id": "" }, "id": "" }

• status: String. Can be "deleted" or "not_found".
• id: String. The ID of the deleted conversation.

4. end_conversation

Ends an existing conversation by setting the ended_at timestamp.

Request

{ "jsonrpc": "2.0", "method": "end_conversation", "params": { "project_id": "", "token": "", "id": "" }, "id": "" }

• id: String. The ID of the conversation to end.

Response

{ "jsonrpc": "2.0", "result": { "status": "", "id": "" }, "id": "" }

• status: String. Can be "ended" or "not_found".
• id: String. The ID of the ended conversation.

Error Handling

If an error occurs, the response will have an "error" field instead of a "result" field:

{ "jsonrpc": "2.0", "error": { "code": , "message": "" }, "id": "" }

Common error codes: - -32700: Parse error - -32600: Invalid Request - -32601: Method not found - -32602: Invalid params - -32603: Internal error - -32000 to -32099: Implementation-defined server errors

Security Considerations

• Ensure that token is kept secure and refreshed periodically.
• Implement rate limiting to prevent abuse.
• Validate and sanitize all data to prevent injection attacks or data corruption.
• Restrict access to webhook URLs to trusted sources to prevent unauthorized data access.

Notes

• The create_conversation method will return an existing conversation if one exists with the given ID, unless reinit is set to true.
• Conversations are stored with their full message history, which is maintained across sessions unless explicitly reinitialized.
• The chat method will auto-create a conversation if it does not exist and a config_url is provided in the request.

Conversation Post-Processing

The AI Chat Service supports post-processing of conversations, which can be configured using post_prompt and post_prompt_url settings. This feature allows for additional processing or summarization of conversation data after a conversation has ended.

Configuration

• post_prompt: A string that defines the prompt or instructions for post-processing the conversation. This can include specific tasks like summarization or analysis of the conversation content.

• post_prompt_url: A URL to which the processed conversation data will be sent. This allows for integration with external systems for further handling or storage of the processed data.

Post-Processing Workflow

1. Trigger: Post-processing is triggered when a conversation ends and is marked for processing.

2. Processing: The conversation data is processed according to the post_prompt instructions. This may involve summarizing the conversation or extracting key insights.

3. Data Format: The processed data is sent to the post_prompt_url in the following JSON format:

   json { "action": "post_conversation", "app_name": "<app_name>", "conversation_id": "<conversation_id>", "call_log": [ { "role": "<role>", "content": "<message_content>" } // ... more messages ], "raw_messages": [ { "role": "<role>", "content": "<raw_message_content>" } // ... more raw messages ], "previous_contexts": [ // previous context data ], "user_meta_data": { // user-specific metadata }, "call_id": "<call_id>", "total_input_tokens": <total_input_tokens>, "total_output_tokens": <total_output_tokens>, "call_start_date": <call_start_date>, "call_end_date": <call_end_date>, "post_prompt_data": { "raw": "<ai_summary>" }, "global_data": { // global data }, "meta_data": { // meta data } }

   • action: Always "post_conversation".
   • app_name: The name of the application, defaulting to a predefined value if not specified.
   • conversation_id: The unique identifier of the conversation.
   • call_log: An array of cleaned message objects, each containing the role and content.
   • raw_messages: An array of raw message objects, each containing the role and content.
   • previous_contexts: An array of previous context data.
   • user_meta_data: User-specific metadata provided during the conversation.
   • call_id: The unique identifier of the call, converted to a string.
   • total_input_tokens: The total number of input tokens used in the conversation.
   • total_output_tokens: The total number of output tokens generated by the AI.
   • call_start_date: The start date of the call, in microseconds since the epoch.
   • call_end_date: The end date of the call, in microseconds since the epoch, or null if not ended.
   • post_prompt_data: Contains the raw AI summary.
   • global_data: Additional global data related to the conversation.
   • meta_data: Additional metadata related to the conversation.

4. Error Handling: If the post-processing or data transmission fails, appropriate error handling and logging are performed to ensure reliability and traceability.

Security Considerations

• Ensure that the post_prompt_url is secure and accessible only to authorized systems.
• Validate and sanitize all data before processing to prevent injection attacks or data corruption.

This section provides an overview of how conversation post-processing is configured and executed, allowing users to leverage additional processing capabilities in their AI chat service.

Debug Webhook

The AI Chat Service provides a debug_webhook_url configuration option to facilitate debugging and monitoring of conversation events. This feature allows developers to receive detailed information about conversation activities in real-time.

Configuration

• debug_webhook_url: A URL to which debug information about conversation events will be sent. This can be used to monitor the flow of conversations, track errors, and gather insights for troubleshooting.

Debug Workflow

1. Trigger: Debug information is sent to the debug_webhook_url whenever significant events occur in a conversation, such as:

   • Processing data maps and actions.
   • Parsing webhooks.
   • Handling errors and exceptions.

2. Data Format: The debug data is sent in the following JSON format:

   json { "action": "<action_type>", "timestamp": "<event_timestamp>", "conversation_id": "<conversation_id>", "details": { // event-specific details }, "error": "<error_message>" // optional }

   • action: The type of action or event (e.g., "process_data_map", "process_action", "parse_webhook").
   • timestamp: The time at which the event occurred.
   • conversation_id: The unique identifier of the conversation.
   • details: Additional details specific to the event, such as data being processed or function arguments.
   • error: An optional field containing error messages if an error occurred during the event.

3. Use Cases: The debug webhook can be used for:

   • Monitoring conversation flow and performance.
   • Capturing errors and exceptions for analysis.
   • Gathering insights into user interactions and system behavior.

Security Considerations

• Ensure that the debug_webhook_url is secure and accessible only to authorized systems.
• Handle and store debug data securely to prevent unauthorized access or data leaks.

This section provides an overview of how the debug webhook is configured and used, enabling developers to gain deeper insights into the operation of their AI chat service.

SWAIG Functions

SWAIG (SignalWire AI Gateway) functions are a powerful feature of the AI Chat Service that enable developers to extend the capabilities of their chat applications through custom logic and data processing. These functions allow for seamless integration with external services, enabling chat applications to perform complex operations and dynamically transform data within conversations.

The SWAIG configuration is typically part of a larger configuration structure that includes:

• post_prompt_url: URL for post-processing prompts
• params: Additional parameters like debug webhook URLs
• prompt: Configuration for the AI prompt, including top_p, temperature, and the prompt text
• post_prompt: Configuration for post-conversation processing

Configuration Format

SWAIG functions are defined within the configuration as follows:

{
  "SWAIG": {
    "defaults": {
      "web_hook_url": "<default_webhook_url>",
      "meta_data_token": "<default_token>"
    },
    "functions": [
      {
        "function": "<function_name>",
        "purpose": "<function_description>",
        "argument": {
          "properties": {
            "<parameter_name>": {
              "type": "<parameter_type>",
              "description": "<parameter_description>"
            }
            // ... more parameters
          }
        },
        "meta_data_token": "<specific_token>",
        "data_map": {
          "output": {
            "action": [
              {
                "set_meta_data": {
                  "key": "value"
                }
              },
              {
                "set_global_data": {
                  "key": "value"
                }
              }
            ],
            "response": "This is the response string."
          },
          "webhooks": [
            {
              "url": "<webhook_url>",
              "method": "GET",
              "params": {
                // Parameters to be sent with the webhook request
              },
              "headers": {
                // Headers to be sent with the webhook request
              },
              "require_args": ["required_arg1", "required_arg2"],
              "error_keys": ["error"],
              "expressions": [
                {
                  "string": "${some_variable}",
                  "pattern": "/regex_pattern/i",
                  "output": {
                    "response": "Response if pattern matches",
                    "action": {
                      "set_meta_data": {
                        "key": "value"
                      }
                    }
                  }
                }
              ],
              "output": {
                "response": "Default webhook response"
              }
            }
            // Additional webhooks can be defined here
          ],
          "foreach": {
            "input_key": "<key_for_input_data>",
            "output_key": "<key_for_output_data>",
            "append": {
              "response": "${this.field1}: ${this.field2}"
            },
            "max": <maximum_items_to_process>
          }
        }
      }
      // Additional functions can be defined here
    ]
  }
}

Key points to note: - The argument field uses properties instead of type: "object" and properties as a subfield. - Webhooks can include headers for API authentication. - Expression outputs can include both response and action fields. - The foreach structure uses append with a simple string template rather than a complex object.

Processing Logic

1. Output Alone: The output section is used to specify the final format of the data after processing. It acts as a template where placeholders are replaced with real data.
2. Webhooks: Allows fetching additional data from external sources. Each webhook can have its own expressions for conditional processing.
3. Expressions: Used for pattern matching and conditional output generation based on webhook responses or input data.
4. Foreach Processing: Enables iterating over lists of data, applying consistent transformations to each item.

Note: The output structure can vary slightly depending on the context. It may include response, action, or both.

Variable Expansion

Variables can be expanded using the ${variable} syntax. The data for these variables comes from: - global_data: Global data available to the conversation - meta_data: Data associated with the meta_data_token - args: Arguments passed to the function - this: Used in foreach loops to refer to the current item - input.args: Arguments passed to the function

Variable expansion can include modifiers, e.g., ${lc:enc:variable} for lowercasing and encoding.

Use Cases

• Data Transformation: Convert input data into a specific output format using dynamic variable expansion.
• External Data Integration: Enhance data processing by integrating external data sources through webhooks.
• Pattern Matching: Use expressions to conditionally generate outputs based on input data.
• Iterative Processing: Use foreach to apply transformations to lists of data.

Security Considerations

• Ensure that all data_map configurations are secure and that data is validated and sanitized to prevent unauthorized access or data manipulation.
• Validate and sanitize inputs used in data_map to prevent injection attacks or malformed data.
• Restrict access to webhook URLs to trusted sources to prevent unauthorized data access.
• Handle and store post-processing and debug data securely to prevent unauthorized access or data leaks.

Normal SWAIG Mode

Example of Normal SWAIG Mode Configuration

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "ai": {
          "post_prompt_url": "<post_prompt_url>",
          "params": {
            "conscience": true
          },
          "prompt": {
            "top_p": 1.0,
            "temperature": 0.3,
            "frequency_penalty": 0.1,
            "presence_penalty": 0.1,
            "text": "Your name is Franklin. You are a weather bot who also knows starwars trivia. - Introduce yourself. Say your name. - See if I have any questions."
          },
          "post_prompt": {
            "top_p": 1.0,
            "temperature": 0.3,
            "frequency_penalty": 0.1,
            "presence_penalty": 0.1,
            "text": "Please summarize the conversation"
          },
          "SWAIG": {
            "defaults": {
              "web_hook_url": "<swaig_webhook_url>"
            },
            "functions": [
              {
                "function": "get_weather",
                "purpose": "To determine what the current weather is in a provided location.",
                "argument": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string",
                      "description": "the location to check the weather in"
                    }
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Key points to note: - The argument field uses type: "object" and properties to define expected parameters. - Webhooks can include headers for API authentication. - Expression outputs can include both response and action fields. - The foreach structure uses append with a simple string template.

Processing Logic

1. Output Alone: The output section is used to specify the final format of the data after processing. It acts as a template where placeholders are replaced with real data.
2. Webhooks: Allows fetching additional data from external sources. Each webhook can have its own expressions for conditional processing.
3. Expressions: Used for pattern matching and conditional output generation based on webhook responses or input data.
4. Foreach Processing: Enables iterating over lists of data, applying consistent transformations to each item.

Note: The output structure can vary slightly depending on the context. It may include response, action, or both.

Variable Expansion

Variables can be expanded using the ${variable} syntax. The data for these variables comes from: - global_data: Global data available to the conversation - meta_data: Data associated with the meta_data_token - args: Arguments passed to the function - this: Used in foreach loops to refer to the current item - input.args: Arguments passed to the function

Variable expansion can include modifiers, e.g., ${lc:enc:variable} for lowercasing and encoding.

Use Cases

• Data Transformation: Convert input data into a specific output format using dynamic variable expansion.
• External Data Integration: Enhance data processing by integrating external data sources through webhooks.
• Pattern Matching: Use expressions to conditionally generate outputs based on input data.
• Iterative Processing: Use foreach to apply transformations to lists of data.

Security Considerations

• Ensure that all data_map configurations are secure and that data is validated and sanitized to prevent unauthorized access or data manipulation.
• Validate and sanitize inputs used in data_map to prevent injection attacks or malformed data.
• Restrict access to webhook URLs to trusted sources to prevent unauthorized data access.
• Handle and store post-processing and debug data securely to prevent unauthorized access or data leaks.

Data Map

The data_map is a crucial component of the SWAIG configuration, enabling complex data processing and integration with external services. It consists of several key elements:

Webhooks

Webhooks allow the AI service to fetch additional data from external sources. Each webhook can be configured with:

• URL: The endpoint to send the request to.
• Method: HTTP method (e.g., GET, POST).
• Params: Parameters to include in the request.
• Headers: Headers for API authentication.
• Require Args: Arguments required for the webhook to execute.
• Error Keys: Keys to identify errors in the response.
• Expressions: Conditional logic to process the response.

Example Function Definition with Webhooks

{
  "function": "fetch_data",
  "purpose": "To fetch data from an external API.",
  "argument": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "The key to fetch data for."
      }
    }
  },
  "data_map": {
    "webhooks": [
      {
        "url": "<webhook_url>",
        "method": "GET",
        "params": {
          "key": "${args.key}"
        },
        "headers": {
          "Authorization": "Bearer <token>"
        },
        "require_args": ["key"],
        "error_keys": ["error"],
        "expressions": [
          {
            "string": "${response.data}",
            "pattern": "/success/i",
            "output": {
              "response": "Data fetched successfully.",
              "action": {
                "set_meta_data": {
                  "data": "${response.data}"
                }
              }
            }
          }
        ],
        "output": {
          "response": "Failed to fetch data."
        }
      }
    ]
  }
}

Expressions

Expressions are used for pattern matching and conditional output generation based on webhook responses or input data. They consist of:

• String: The data to evaluate.
• Pattern: The regex pattern to match.
• Output: The result if the pattern matches, including response and action.

Example Function Definition with Expressions

{
  "function": "process_data",
  "purpose": "To process data based on pattern matching.",
  "argument": {
    "type": "object",
    "properties": {
      "input": {
        "type": "string",
        "description": "The input data to process."
      }
    }
  },
  "data_map": {
    "expressions": [
      {
        "string": "${args.input}",
        "pattern": "/match/i",
        "output": {
          "response": "Pattern matched successfully.",
          "action": {
            "set_meta_data": {
              "matched": "true"
            }
          }
        }
      }
    ],
    "output": {
      "response": "No match found."
    }
  }
}

Foreach Processing

The foreach structure allows iterating over lists of data, applying transformations to each item. It includes:

• Input Key: The key for the input data list.
• Output Key: The key for the output data list.
• Append: Template for each item.
• Max: Maximum items to process.

Example Function Definition with Foreach

{
  "function": "summarize_items",
  "purpose": "To summarize a list of items.",
  "argument": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "description": "The list of items to summarize."
      }
    }
  },
  "data_map": {
    "foreach": {
      "input_key": "items",
      "output_key": "summaries",
      "append": {
        "response": "Item: ${this.name}, Value: ${this.value}"
      },
      "max": 5
    }
  }
}

Output

The output section specifies the final format of the data after processing. It can include:

• Response: The response string.
• Actions: Actions to perform, such as setting metadata.

Variable Expansion

Variables can be expanded using the ${variable} syntax. Sources for these variables include:

• Global Data: Available to the conversation.
• Meta Data: Associated with the meta_data_token.
• Args: Arguments passed to the function.
• This: Refers to the current item in foreach loops.
• Input Args: Arguments passed to the function.

Example

{
  "response": "Hello, ${args.user_name}! The current time is ${global_data.current_time}."
}

Use Cases

• Data Transformation: Convert input data into a specific output format using dynamic variable expansion.
• External Data Integration: Enhance data processing by integrating external data sources through webhooks.
• Pattern Matching: Use expressions to conditionally generate outputs based on input data.
• Iterative Processing: Use foreach to apply transformations to lists of data.

Security Considerations

• Ensure that all data_map configurations are secure and that data is validated and sanitized to prevent unauthorized access or data manipulation.
• Validate and sanitize inputs used in data_map to prevent injection attacks or malformed data.
• Restrict access to webhook URLs to trusted sources to prevent unauthorized data access.
• Handle and store post-processing and debug data securely to prevent unauthorized access or data leaks.