Chat API

Endpoint

POST https://app.askapollohq.com/v1/chat/:id

id string : The Unique Id of the chatbot.

Request Headers

The API request must include the following headers:

• Authorization: Bearer <Your-Secret-API-Key> The secret API key for authenticating the API request.
• Content-Type: application/json The content type of the request payload.

Request Body

{
  "messages": [
    { "content": "How can I help you?", "role": "assistant" },
    { "content": "What is AskApollo?", "role": "user" }
  ],
  "stream": false,
  "creativity": 0,
  "conversation_id": "<Conversation Id>"
}

The request body should contain the following parameters:

messages array required

A list of messages

content string required

Represents the text content of the message.

role string required

Can take one of the value -> "user" or "assistant".

stream boolean required

If set to true, words will be sent back as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message. If set to false, the full response will be returned once it's ready.

creativity number optional

Valid value between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

conversation_id string optional

This is Id of the current conversation. If specified the conversation will be saved to the chatbot dashboard. If not provided, the conversation will not be saved. This Id should be generated on calling system. Different Ids for should be generated for different conversations. To save messages to same conversation make requests using the same Id.

Response body (non streaming)

For non streaming response the API will return JSON with following parameters:

content string;

This is the response text.

role string;

Will always be set to assistant

{"content": "How are you today. How can I help you?", "role": "assistant"}

Example request without streaming

const response = await fetch('https://app.askapollohq.com/api/v1/chat/e9673cd9-...-10dc93bd57cdw', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer 4Mo56...w7L8k'
  },
  body: JSON.stringify({
    messages: [
      { content: 'How can I help you?', role: 'assistant' },
      { content: 'What is AskApollo?', role: 'user' }
    ],
    stream: false,
    creativity: 0
  })
});
 
if (!response.ok) {
  const errorData = await response.json();
  throw Error(errorData.message);
}
const data = await response.json(); 
console.log(data);

Streaming

If the stream parameter is set to true, The Chat API will stream responses back. We follow the Server-sent events (opens in a new tab) standard for this. Below is the code snippet to read the stream:

const response = await fetch('https://app.askapollohq.com/api/v1/chat/e9673cd9-...-10dc93bd57cdw', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer 4Mo56...w7L8k'
  },
  body: JSON.stringify({
    messages: [
      { content: 'How can I help you?', role: 'assistant' },
      { content: 'What is AskApollo?', role: 'user' }
    ],
    stream: true,
    creativity: 0,
  })
});
 
if (!response.ok) {
  const errorData = await response.json();
  throw Error(errorData.message);
}
 
const data = response.body;
 
if (!data) {
  throw Error("no data available");
}
 
const reader = data.getReader();
const decoder = new TextDecoder();
let done = false;
 
while (!done) {
  const { value, done: doneReading } = await reader.read();
  done = doneReading;
  const chunkValue = decoder.decode(value);
  //log the chunks received
  console.log(chunkValue); 
}

Save Conversations

To save the conversations on the AskApollo platform include conversation_id parameter in the request. The full conversation should be sent on every API call to save all previous messages. The messages received in the latest API call for a given converstion_id overrides the conversation already saved on the platform.

Error Handling

Appropriate HTTP status codes will be returned along with error messages in the response body. Make sure to handle these errors gracefully in your application.