Canonical Voice API Docs

Below you will find examples on how to use our API. This endpoint puts the recording on the queue for background processing so you will get a fast 200 OK response with nothing really interesting. The endpoint response is as follows:

Contact Support

If you need assistance or have any questions about our API, please don't hesitate to contact our support team at support@canonical.chat.

{
  "callId": "25d739ee-413d-4159-b6a6-35b9da9bcee1"
}
          

Request JSON Schema

schema: {
  body: {
    type: 'object',
    required: ['assistant', 'location', 'callId'],
    properties: {
      assistant: {
        type: 'object',
        required: ['id', 'speaksFirst'],
        properties: {
          id: { type: 'string' },
          speaksFirst: { type: 'boolean' },
          description: { type: 'string' }
        }
      },
      callId: { type: 'string' },
      location: { type: 'string' },
    }
  }
}
          

Curl

curl -X POST 'https://voiceapp.canonical.chat/api/v1/call' \
     -H 'Content-Type: application/json' \
     -H 'X-Canonical-Api-Key: YOUR_API_KEY_HERE' \
     -d '{
       "assistant": {
         "id": "UNIQUE_ID_FOR_THE_ASSISTANT",   # you will use this to select between different AI agents on our dashboard (e.g., Voicebot v0.1)
         "speaksFirst": true,                   # if the AI agent speaks first in the call, then set to true
         "description": "Outbound Sales Agent"  # optional friendly name or description for the assistant
       },
       "location": "ACCESSIBLE_URL_TO_AUDIO_FILE",
       "callId": "YOUR_CALL_ID"                 # use this to to map the call back to your system
     }'
          

JavaScript

const axios = require('axios');
const CANONICAL_API = 'https://voiceapp.canonical.chat';
const HEADERS = {
  'Content-Type': 'application/json',
  'X-Canonical-Api-Key': process.env.CANONICAL_API_KEY
};

async function main() {
  const response = await axios.post(
    `${CANONICAL_API}/api/v1/call`,
    {
      assistant: {
        id: "UNIQUE_ID_FOR_THE_ASSISTANT",      // you will use this to select between different AI agents on our dashboard (e.g., Voicebot v0.1)
        speaksFirst: true,                      // if the AI agent speaks first in the call, then set to true
        description: "Outboun Sales Agent"      // optional friendly name or description for the assistant
      },
      location: "ACCESSIBLE_URL_TO_AUDIO_FILE",
      callId: "YOUR_CALL_ID"                    // use this to to map the call back to your system
    },
    { headers: HEADERS }
  );
  console.log(response.data);
}

main().catch(console.error);
          

Python

import os
import requests

CANONICAL_API = 'https://voiceapp.canonical.chat'
HEADERS = {
    'Content-Type': 'application/json',
    'X-Canonical-Api-Key': os.environ.get('CANONICAL_API_KEY')
}

def main():
    try:
        response = requests.post(
            f"{CANONICAL_API}/api/v1/call",
            json={
                "assistant": {
                    "id": "UNIQUE_ID_FOR_THE_ASSISTANT",      # you will use this to select between different AI agents on our dashboard (e.g., Voicebot v0.1)
                    "speaksFirst": True,                      # if the AI agent speaks first in the call, then set to true
                    "description": "Outbound Sales Agent"     # optional friendly name or description for the assistant
                },
                "location": "ACCESSIBLE_URL_TO_AUDIO_FILE",
                "callId": "YOUR_CALL_ID"                      # use this to to map the call back to your system
            },
            headers=HEADERS
        )
        response.raise_for_status()
        print(response.json())
    except requests.RequestException as error:
        print(f"Error: {str(error)}")

if __name__ == "__main__":
    main()
          

Retell Integration

Simply send a POST request to the endpoint with the JSON body from Retell's call_analyzed event. Note, you will get a 200 OK with an error attribute in the response JSON if the event is not call_analyzed.

curl -X POST 'https://voiceapp.canonical.chat/api/v1/webhooks/retell' \
     -H 'Content-Type: application/json' \
     -H 'X-Canonical-Api-Key: YOUR_API_KEY_HERE' \
     -d 'RETELL_EVENT_BODY_HERE'