API

An API allows external systems to communicate directly with your agent through secure, programmatic endpoints. This channel enables integration of your VIVI agent into custom applications, backend systems, or third-party workflows using standard HTTP-based requests. When you create a new API channel, VIVI generates a unique set of credentials and documentation including a channel ID and API key. You’ll also receive auto-generated OpenAPI/Swagger documentation that details the available endpoints, request structures, and required parameters.

Endpoints

In order to test the endpoints, you will need to assign your API channel to an agent. Once assigned, head back to the API channel page and click Test to view the testing window. VIVI provides five endpoints:

Stream Messages
Invoke Messages
Batch Messages
Files

POST

https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/stream
This endpoint allows you to stream a single message in a conversation channel.

apiKey

string

required

The API key given to you when creating your API channel.

channelId

string

required

The Channel ID given to you when creating your API channel.

message

string

required

The test message that you’d like to send to the agent.

threadId

UUID

required

The custom thread ID to use for the conversation.

userId

UUID

The custom user ID that will be associated with this user.

attachedFiles

string

The URL you received from the Upload Conversation Files endpoint.

Request

import requests

channelId = "channelId"
apiKey = "apiKey"

url = f"https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/stream"

headers = {
    "Content-Type": "application/json",
    "vivi-api-key": apiKey
}

data = {
    "message": "your sample message",
    "threadId": "conversationId",
    "userId": None, # optional
	"attachedFiles": None # alternatively, if you uploaded files, insert the Uploaded Files URL here, ex: ['https://urlpath']
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Don’t forget to swap the apiKey and channelId with your credentials.

Response

data: {"message": "", "event": "on_chat_model_start"}
data: {"message": "Hello", "event": "on_chat_model_stream"}
data: {"message":"","event":"on_chat_model_end"}

POST

https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/invoke
This endpoint allows you to receive the full message at one time instead of streaming it incrementally.

apiKey

string

required

The API key given to you when creating your API channel.

channelId

string

required

The Channel ID given to you when creating your API channel.

message

string

required

The test message that you’d like to send to the agent.

threadId

UUID

required

The custom thread ID to use for the conversation.

userId

UUID

The custom user ID that will be associated with this user.

attachedFiles

string

The URL you received from the Upload Conversation Files endpoint.

Request

import requests

channelId = "channelId"
apiKey = "apiKey"

url = f"https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/invoke"

headers = {
    "Content-Type": "application/json",
    "vivi-api-key": apiKey
}

data = {
    "message": "your sample message",
    "threadId": "conversationId",
    "userId": None, # optional
	"attachedFiles": None # alternatively, if you uploaded files, insert the Uploaded Files URL here, ex: ['https://urlpath']
}

response = requests.post(url, headers=headers, json=data)

try:
    print(response.json())
except Exception:
    print(response.text)

Don’t forget to swap the apiKey and channelId with your credentials.

Response

{'message': "Hello world!",'event': None}

POST

https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/batch
This endpoint allows you to send multiple messages at one time.

apiKey

string

required

The API key given to you when creating your API channel.

channelId

string

required

The Channel ID given to you when creating your API channel.

message

string

required

The test message that you’d like to send to the agent.

threadId

UUID

required

The custom thread ID to use for the conversation.

userId

UUID

The custom user ID that will be associated with this user.

attachedFiles

string

The URL you received from the Upload Conversation Files endpoint.

Request

import requests

channelId = "channelId"
apiKey = "apiKey"

url = f"https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/batch"

headers = {
    "Content-Type": "application/json",
    "vivi-api-key": apiKey
}

data = [{
    "message": "your sample message",
    "threadId": "conversationId",
    "userId": None, # optional
	"attachedFiles": None # alternatively, if you uploaded files, insert the Uploaded Files URL here, ex: ['https://urlpath']
}]

response = requests.post(url, headers=headers, json=data)

for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Don’t forget to swap the apiKey and channelId with your credentials.

Response

[{"message":"Hello world!","event":null},
{"message":"Hello world again!","event":null}]

Upload Conversation Files

POST

https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/files
This endpoint allows you to upload files to use during your conversation.

apiKey

string

required

The API key given to you when creating your API channel.

channelId

string

required

The Channel ID given to you when creating your API channel.

Request

import requests

channelId = "channelId"
apiKey = "apiKey"

url = f"https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/files"

headers = {
    "vivi-api-key": apiKey
}

# Replace 'test_document.pdf' with actual file path
files = {'files': open('test_document.pdf', 'rb')}

response = requests.post(url, headers=headers, files=files)
print(f"Status Code: {response.status_code}")
if response.status_code == 201:
    data = response.json()
    print("Uploaded Files:", data.get("uploadedFiles", []))
else:
    print("Error:", response.text)

files['files'].close()

Don’t forget to swap the apiKey and channelId with your credentials.

Response

Status Code: 201
Uploaded Files: [fileURL]

Get Files Extensions

GET

https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/files/extensions
This endpoint allows you to verify available file extensions.

apiKey

string

required

The API key given to you when creating your API channel.

channelId

string

required

The Channel ID given to you when creating your API channel.

Request

  import requests

  channelId = "channelId"
  apiKey = "apiKey"

  url = f"https://api-prod-d1d739d4-c24f-59dc-865b-e630d70bf11b.vivi.bot/channelsApi/{channelId}/files/extensions"

  headers = {
  "vivi-api-key": apiKey
  }

response = requests.get(url, headers=headers)
print(f"Status Code: {response.status_code}")
if response.status_code == 200:
  data = response.json()
  print("Supported Extensions:", data.get("supportedFileExtensions", []))
else:
  print("Error:", response.text)

Don’t forget to swap the apiKey and channelId with your credentials.

Response

Status Code: 200
Supported Extensions: [{'extension': '.mp3', 'maxFileSizeInMb': 20, 'mimeType': 'audio/mpeg', 'category': 'audio'}, {'extension': '.wav', 'maxFileSizeInMb': 20, 'mimeType': 'audio/x-wav', 'category': 'audio'}, {'extension': '.pdf', 'maxFileSizeInMb': 10, 'mimeType': 'application/pdf', 'category': 'formatted_docs'}, {'extension': '.xls', 'maxFileSizeInMb': 10, 'mimeType': 'application/vnd.ms-excel', 'category': 'formatted_docs'}, {'extension': '.xlsx', 'maxFileSizeInMb': 10, 'mimeType': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'category': 'formatted_docs'}, {'extension': '.docx', 'maxFileSizeInMb': 10, 'mimeType': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'category': 'formatted_docs'}, {'extension': '.pptx', 'maxFileSizeInMb': 10, 'mimeType': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'category': 'formatted_docs'}, {'extension': '.bmp', 'maxFileSizeInMb': 20, 'mimeType': 'image/bmp', 'category': 'image'}, {'extension': '.gif', 'maxFileSizeInMb': 20, 'mimeType': 'image/gif', 'category': 'image'}, {'extension': '.jpeg', 'maxFileSizeInMb': 20, 'mimeType': 'image/jpeg', 'category': 'image'}, {'extension': '.jpg', 'maxFileSizeInMb': 20, 'mimeType': 'image/jpeg', 'category': 'image'}, {'extension': '.png', 'maxFileSizeInMb': 20, 'mimeType': 'image/png', 'category': 'image'}, {'extension': '.svg', 'maxFileSizeInMb': 20, 'mimeType': 'image/svg+xml', 'category': 'image'}, {'extension': '.tiff', 'maxFileSizeInMb': 20, 'mimeType': 'image/tiff', 'category': 'image'}, {'extension': '.webp', 'maxFileSizeInMb': 20, 'mimeType': 'image/webp', 'category': 'image'}, {'extension': '.heif', 'maxFileSizeInMb': 20, 'mimeType': 'image/heif', 'category': 'image'}, {'extension': '.txt', 'maxFileSizeInMb': 3, 'mimeType': 'text/plain', 'category': 'lightweight_text'}, {'extension': '.md', 'maxFileSizeInMb': 3, 'mimeType': 'text/markdown', 'category': 'lightweight_text'}, {'extension': '.py', 'maxFileSizeInMb': 3, 'mimeType': 'text/x-python', 'category': 'lightweight_text'}, {'extension': '.go', 'maxFileSizeInMb': 3, 'mimeType': 'text/x-go', 'category': 'lightweight_text'}, {'extension': '.csv', 'maxFileSizeInMb': 3, 'mimeType': 'text/csv', 'category': 'lightweight_text'}, {'extension': '.tsv', 'maxFileSizeInMb': 3, 'mimeType': 'text/tab-separated-values', 'category': 'lightweight_text'}, {'extension': '.html', 'maxFileSizeInMb': 3, 'mimeType': 'text/html', 'category': 'lightweight_text'}, {'extension': '.htm', 'maxFileSizeInMb': 3, 'mimeType': 'text/html', 'category': 'lightweight_text'}, {'extension': '.xml', 'maxFileSizeInMb': 3, 'mimeType': 'application/xml', 'category': 'lightweight_text'}, {'extension': '.json', 'maxFileSizeInMb': 3, 'mimeType': 'application/json', 'category': 'lightweight_text'}, {'extension': '.ndjson', 'maxFileSizeInMb': 3, 'mimeType': 'application/x-ndjson', 'category': 'lightweight_text'}, {'extension': '.yaml', 'maxFileSizeInMb': 3, 'mimeType': 'application/yaml', 'category': 'lightweight_text'}, {'extension': '.yml', 'maxFileSizeInMb': 3, 'mimeType': 'application/yaml', 'category': 'lightweight_text'}, {'extension': '.epub', 'maxFileSizeInMb': 3, 'mimeType': 'application/epub+zip', 'category': 'lightweight_text'}, {'extension': '.eml', 'maxFileSizeInMb': 3, 'mimeType': 'message/rfc822', 'category': 'lightweight_text'}, {'extension': '.p7s', 'maxFileSizeInMb': 3, 'mimeType': 'application/pkcs7-signature', 'category': 'lightweight_text'}, {'extension': '.msg', 'maxFileSizeInMb': 3, 'mimeType': 'application/vnd.ms-outlook', 'category': 'lightweight_text'}, {'extension': '.pst', 'maxFileSizeInMb': 3, 'mimeType': 'application/vnd.ms-outlook-pst', 'category': 'lightweight_text'}, {'extension': '.ipynb', 'maxFileSizeInMb': 3, 'mimeType': 'application/x-ipynb+json', 'category': 'lightweight_text'}]

Best Practices

Keep your API key secret and rotate it if you suspect exposure.
Always test endpoints using the provided tools before connecting production systems.

Getting Started

Core Concepts

Accounts & Billing

Features

Resources

Endpoints

Upload Conversation Files

Get Files Extensions

Best Practices

Getting Started

Core Concepts

Accounts & Billing

Features

Resources

​Endpoints

​Upload Conversation Files

​Get Files Extensions

​Best Practices

Endpoints

Upload Conversation Files

Get Files Extensions

Best Practices