Skip to main content
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"}

​
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.