Vendasta Conversation API
Conversations AI service API for the unified inbox that centralises SMS, web chat, voice and other channels. Scope-gated with `conversation`, `conversation:read` and `conversation.widget`.
OpenAPI Specification
{
"components": {
"schemas": {
"conversationv1PagedResponseMetadata": {
"properties": {
"hasMore": {
"title": "Whether or not more results exist",
"type": "boolean"
},
"nextCursor": {
"title": "A cursor that can be provided to retrieve the next page of results",
"type": "string"
},
"totalResults": {
"format": "int64",
"title": "Total number of results",
"type": "string"
}
},
"type": "object"
},
"googlerpcStatus": {
"properties": {
"code": {
"format": "int32",
"type": "integer"
},
"details": {
"items": {
"$ref": "#/components/schemas/protobufAny"
},
"type": "array"
},
"message": {
"type": "string"
}
},
"type": "object"
},
"protobufAny": {
"additionalProperties": {},
"properties": {
"@type": {
"type": "string"
}
},
"type": "object"
},
"v1CommunicationChannelType": {
"default": "COMMUNICATION_CHANNEL_TYPE_UNDEFINED",
"enum": [
"COMMUNICATION_CHANNEL_TYPE_UNDEFINED",
"COMMUNICATION_CHANNEL_TYPE_SMS",
"COMMUNICATION_CHANNEL_TYPE_VOICE"
],
"title": "Channel types for communication info",
"type": "string"
},
"v1CommunicationInfo": {
"properties": {
"channel": {
"$ref": "#/components/schemas/v1CommunicationChannelType"
},
"identifier": {
"title": "The identifier for this channel (phone number, email, etc.)",
"type": "string"
}
},
"title": "Information about a communication channel",
"type": "object"
},
"v1ListCommunicationChannelsInfoRequest": {
"properties": {
"accountGroupId": {
"title": "The account group ID to look up communication info for",
"type": "string"
}
},
"title": "Request to list communication channel info for a business",
"type": "object"
},
"v1ListCommunicationChannelsInfoResponse": {
"properties": {
"communicationInfo": {
"items": {
"$ref": "#/components/schemas/v1CommunicationInfo"
},
"title": "The list of communication info for this account",
"type": "array"
}
},
"title": "Response containing communication channel information",
"type": "object"
},
"v1ListWidgetsResponse": {
"properties": {
"pagingMetadata": {
"$ref": "#/components/schemas/conversationv1PagedResponseMetadata"
},
"widgets": {
"items": {
"$ref": "#/components/schemas/v1Widget"
},
"title": "The list of widgets",
"type": "array"
}
},
"type": "object"
},
"v1Widget": {
"properties": {
"accentColor": {
"title": "Accent color for the widget secondary elements",
"type": "string"
},
"accentTextColor": {
"title": "Accent text color for the widget secondary elements",
"type": "string"
},
"additionalPromptInstructions": {
"title": "The prompt provided by a user to be used as additional instructions for the web chat AI assistant",
"type": "string"
},
"allowedUrls": {
"items": {
"type": "string"
},
"title": "A list of urls that the widget is allowed to be embedded on",
"type": "array"
},
"assistantAvatarUrl": {
"title": "The avatar URL of the AI assistant",
"type": "string"
},
"assistantId": {
"readOnly": true,
"title": "Output only. The ID of the AI assistant associated with this widget",
"type": "string"
},
"assistantName": {
"title": "The name of the AI assistant",
"type": "string"
},
"associatedNamespaces": {
"description": "AG namespaces this widget routes to. Only set when widget_type = \"group\".",
"items": {
"type": "string"
},
"type": "array"
},
"color": {
"title": "A hex color code for the widget, e.g. \"#FF0000\"",
"type": "string"
},
"created": {
"format": "date-time",
"title": "The timestamp when the widget was created",
"type": "string"
},
"customGreetingMessage": {
"title": "The custom greeting message that shows up as first message",
"type": "string"
},
"embedHistory": {
"items": {
"type": "string"
},
"title": "The history of widget installations (typically the domain/hostname of the referer URL the widget is embedded on)",
"type": "array"
},
"enableGreetingMessage": {
"title": "Enable the greeting message from AI assistant using the custom greeting message",
"type": "boolean"
},
"hideMobileCta": {
"title": "Hide the popup CTA on mobile screens",
"type": "boolean"
},
"isEnabled": {
"title": "Whether the webchat for the widget config is enabled",
"type": "boolean"
},
"name": {
"title": "Name of the widget, e.g. \"Mountain Media Support\"",
"type": "string"
},
"namespace": {
"title": "The id of the namespace, e.g. \"ABC\", \"AG-123\"",
"type": "string"
},
"position": {
"$ref": "#/components/schemas/v1WidgetPosition"
},
"skipContactCapture": {
"title": "Whether the widget has contact capturing enabled",
"type": "boolean"
},
"textColor": {
"title": "The primary text color for the widget",
"type": "string"
},
"updated": {
"format": "date-time",
"title": "The timestamp when the widget was updated",
"type": "string"
},
"welcomeMessage": {
"title": "The welcome message for the webchat for the widget config",
"type": "string"
},
"widgetId": {
"title": "The id of the widget",
"type": "string"
},
"widgetType": {
"description": "The type of the widget. Examples are: 'inbox', 'my-listings', 'snapshot', 'group', etc.\n'group' is a multi-location widget scoped to a brand (G-xxx) namespace.",
"type": "string"
}
},
"type": "object"
},
"v1WidgetPosition": {
"default": "WIDGET_POSITION_UNSPECIFIED",
"description": "- WIDGET_POSITION_UNSPECIFIED: Unspecified widget position\n - WIDGET_POSITION_RIGHT: Widget position on the right side of the page\n - WIDGET_POSITION_LEFT: Widget position on the left side of the page",
"enum": [
"WIDGET_POSITION_UNSPECIFIED",
"WIDGET_POSITION_RIGHT",
"WIDGET_POSITION_LEFT"
],
"type": "string"
}
},
"securitySchemes": {
"OAuth2": {
"flows": {
"authorizationCode": {
"authorizationUrl": "https://sso-api-prod.apigateway.co/oauth2/auth",
"scopes": {
"business-app": "Allows the application to manage all features of Business App",
"conversation": "Allows the application to manage conversations",
"conversation.widget": "Allows the application to manage conversation widgets",
"conversation:read": "Allows the application view-only access to conversations"
},
"tokenUrl": "https://sso-api-prod.apigateway.co/oauth2/token"
}
},
"type": "oauth2"
}
}
},
"info": {
"title": "Conversation",
"version": "0.236.0"
},
"openapi": "3.0.0",
"paths": {
"/v1/conversation/communication-channels-info": {
"post": {
"operationId": "ConversationService_ListCommunicationChannelsInfo",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v1ListCommunicationChannelsInfoRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v1ListCommunicationChannelsInfoResponse"
}
}
},
"description": "A successful response."
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googlerpcStatus"
}
}
},
"description": "An unexpected error response."
}
},
"security": [
{
"OAuth2": [
"conversation:read",
"conversation",
"business-app"
]
}
],
"summary": "List communication channels info for a business",
"tags": [
"ConversationService"
]
}
},
"/v1beta/widgets": {
"get": {
"operationId": "ConversationService_ListWidgets",
"parameters": [
{
"description": "The namespace of the widget e.g. \"ABC\", \"AG-123\"\nUse either namespace or options.namespaces",
"in": "query",
"name": "namespace",
"schema": {
"type": "string"
}
},
{
"description": "cursor can be passed to retrieve the next page of results keyed by the cursor",
"in": "query",
"name": "pagingOptions.cursor",
"schema": {
"type": "string"
}
},
{
"description": "page_size specifies the number of items to return in the next page",
"in": "query",
"name": "pagingOptions.pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
},
{
"description": "The namespaces of the widgets e.g. \"ABC\", \"AG-123\"\nUse either namespace or options.namespaces",
"explode": true,
"in": "query",
"name": "options.namespaces",
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
},
{
"description": "The types of the widget e.g. \"inbox-pro\", \"my-listings\"",
"explode": true,
"in": "query",
"name": "options.widgetTypes",
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v1ListWidgetsResponse"
}
}
},
"description": "A successful response."
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googlerpcStatus"
}
}
},
"description": "An unexpected error response."
}
},
"security": [
{
"OAuth2": [
"business-app",
"conversation.widget"
]
}
],
"summary": "List widgets",
"tags": [
"ConversationService"
]
}
}
},
"servers": [
{
"description": "Production",
"url": "https://prod.apigateway.co/grpc"
}
],
"tags": [
{
"name": "ConversationService"
}
]
}