SDKs & Integrations Libraries and no-code connectors

SDKs & Integrations

Official libraries, community wrappers, and no-code connectors to integrate ConvoAI into your stack — from a Python microservice to a Zapier automation, with no additional infrastructure required.

Python SDK

A thin, typed wrapper around the ConvoAI REST API. Requires Python 3.9+.

Installation
pip install convoai
Initialise client
from convoai import ConvoAI client = ConvoAI(api_key="ck_live_…") # All resources are available as attributes client.agents # Agents resource client.conversations # Conversations resource client.contacts # Contacts resource client.knowledge # Knowledge Base resource client.messages # Messages resource client.analytics # Analytics resource
Send a message
from convoai import ConvoAI client = ConvoAI(api_key="ck_live_…") # Send a text message to a contact message = client.messages.send( agent_id="ag_01J8X…", to="+15551234567", text="Hi! Your order #4821 has shipped. Track it at track.example.com/4821", ) print(message.id) # msg_01J9…
List and filter conversations
from convoai import ConvoAI client = ConvoAI(api_key="ck_live_…") # Paginate through open conversations page = client.conversations.list( agent_id="ag_01J8X…", status="open", limit=50, ) for conv in page.results: print(conv.id, conv.contact.name, conv.last_message_at) # Fetch next page if page.next_cursor: next_page = client.conversations.list( agent_id="ag_01J8X…", cursor=page.next_cursor, )
Add a document to the knowledge base
from convoai import ConvoAI client = ConvoAI(api_key="ck_live_…") # Upload a text document doc = client.knowledge.create( agent_id="ag_01J8X…", title="Shipping Policy Q2 2026", content="We ship to 45 countries. Standard delivery is 5–7 business days…", metadata={"category": "shipping", "version": "2"}, ) print(f"Document {doc.id} — status: {doc.status}") # indexing | ready # Upload a PDF file with open("returns-policy.pdf", "rb") as f: doc = client.knowledge.create( agent_id="ag_01J8X…", title="Returns Policy", file=f, file_type="pdf", )
Handle webhooks with the SDK
from convoai import ConvoAI, WebhookSignatureError client = ConvoAI(api_key="ck_live_…") def handle_webhook(raw_body: bytes, sig_header: str): try: event = client.webhooks.construct_event( payload=raw_body, sig_header=sig_header, secret="your-webhook-secret", ) except WebhookSignatureError: return 403 # Invalid signature if event.type == "message.received": print("New message from:", event.data["contact_id"]) elif event.type == "handoff.requested": print("Handoff requested — priority:", event.data["priority"]) notify_human_team(event.data) return 200

JavaScript / TypeScript SDK

Fully typed. Works in Node.js 18+ and edge runtimes (Cloudflare Workers, Vercel Edge Functions, Deno). ESM and CJS bundles provided.

Installation
npm install @convoai/sdk # or pnpm add @convoai/sdk
Initialise and send a message — TypeScript
import { ConvoAI } from '@convoai/sdk'; const client = new ConvoAI({ apiKey: process.env.CONVOAI_API_KEY }); // Send a text message const message = await client.messages.send({ agentId: 'ag_01J8X…', to: '+15551234567', text: 'Hi! Your order #4821 has shipped.', }); console.log(message.id); // msg_01J9… // Send a template message (outside 24-hour window) const tmpl = await client.messages.send({ agentId: 'ag_01J8X…', to: '+15551234567', template: { name: 'order_shipped', language: 'en_US', components: [ { type: 'body', parameters: [{ type: 'text', text: '4821' }] }, ], }, });
Upsert a contact and update CRM stage
import { ConvoAI } from '@convoai/sdk'; const client = new ConvoAI({ apiKey: process.env.CONVOAI_API_KEY }); // Upsert by phone — creates if new, updates if exists const contact = await client.contacts.upsert({ agentId: 'ag_01J8X…', phone: '+15551234567', name: 'Maria Garcia', email: 'maria@example.com', stage: 'qualified', tags: ['vip', 'spanish'], customFields: { plan: 'enterprise', region: 'latam' }, }); console.log(contact.id, contact.created); // con_01J9… false (updated)
Verify webhooks — Next.js App Router
// app/api/webhooks/convoai/route.ts import { ConvoAI, WebhookSignatureError } from '@convoai/sdk'; import { NextRequest, NextResponse } from 'next/server'; const client = new ConvoAI({ apiKey: process.env.CONVOAI_API_KEY! }); export async function POST(req: NextRequest) { const rawBody = await req.text(); const sig = req.headers.get('x-convoai-signature') ?? ''; let event; try { event = client.webhooks.constructEvent(rawBody, sig, process.env.CONVOAI_WEBHOOK_SECRET!); } catch (err) { if (err instanceof WebhookSignatureError) { return NextResponse.json({ error: 'Invalid signature' }, { status: 403 }); } throw err; } if (event.type === 'handoff.requested') { await notifySlack(event.data); } return NextResponse.json({ received: true }); }

Zapier Integration

Connect ConvoAI to 6,000+ apps without writing code. The ConvoAI app on Zapier provides triggers for incoming events and actions to send messages or update contacts.

1
Find the ConvoAI app

In Zapier, search for "ConvoAI" in the app directory. Click Connect a new account and paste your ConvoAI API key from the dashboard (Settings → API Keys).

2
Choose a trigger or action
Triggers (events from ConvoAI)
  • New Inbound Message
  • New Conversation
  • Handoff Requested
  • Contact Updated
  • Conversation Closed
Actions (send data to ConvoAI)
  • Send Text Message
  • Send Template Message
  • Create or Update Contact
  • Add Knowledge Document
  • Close Conversation
3
Map fields and turn on your Zap

Use Zapier's field mapper to connect ConvoAI data to your destination app (CRM, spreadsheet, Slack, etc.). Test the step, then turn on the Zap — it runs automatically from that point.

Popular Zap: When a handoff.requested event fires in ConvoAI, create a card in Trello, post a message in Slack with the AI summary, and update the contact stage in HubSpot — all in a single Zap.

Make.com Integration

Make's visual canvas lets you build advanced multi-step workflows with branching, loops, and data transformations — without code.

1
Add the ConvoAI module

In a new or existing Make scenario, click the + button and search for "ConvoAI". Select Watch Events (for triggers) or Send a Message (for actions). Authenticate using your API key.

2
Configure the webhook trigger

Make automatically generates a unique webhook URL. Copy it, then register it in ConvoAI: Settings → Webhooks → New Webhook. Select the events you want to receive.

3
Build your scenario

Chain additional modules (Google Sheets, Salesforce, Slack, email, HTTP) after the ConvoAI trigger. Use Make's data mapping to pass conversation data between steps. Activate your scenario when ready.

Example: Use Make HTTP module as fallback (any language)
// Make HTTP module — send a ConvoAI message from a scenario URL: https://app.convoai.cloud/api/v1/agents/ag_01J8X…/messages/ Method: POST Headers: Authorization: Bearer ck_live_… Content-Type: application/json Body (raw JSON): { "to": "", "type": "text", "text": "Hi , your appointment is confirmed for ." }

n8n Integration

n8n is a self-hosted (or cloud) workflow automation tool. Use the native ConvoAI node or the HTTP Request node to integrate with any ConvoAI endpoint.

1
Set up credentials

In n8n, go to Credentials → New → Header Auth. Set the name to Authorization and the value to Bearer ck_live_…. Save as "ConvoAI API".

2
Use the Webhook trigger node

Add a Webhook node as your workflow trigger. Copy the production webhook URL n8n generates, then register it in ConvoAI (Settings → Webhooks). Set authentication to "Header Auth" and verify the X-ConvoAI-Signature header in a Code node for security.

3
Call the API with HTTP Request node

Add an HTTP Request node after your trigger or in any part of your workflow. Select your ConvoAI API credential, set the method and URL, and use n8n expressions to inject dynamic data from previous nodes.

n8n Code node — verify HMAC signature
// Paste into an n8n Code node (JavaScript mode) immediately after the Webhook node const crypto = require('crypto'); const secret = 'your-webhook-secret'; const sigHeader = $input.first().headers['x-convoai-signature'] ?? ''; const rawBody = JSON.stringify($input.first().body); const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); if (expected !== sigHeader) { throw new Error('Invalid ConvoAI webhook signature'); } // Pass the body through to the next node return $input.all();

REST API — Any Language

No SDK? No problem. Every ConvoAI feature is reachable over standard HTTP. Here are quick examples in common languages.

PHP
<?php $ch = curl_init('https://app.convoai.cloud/api/v1/agents/ag_01J8X…/messages/'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ck_live_…', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'to' => '+15551234567', 'type' => 'text', 'text' => 'Hello from PHP!', ]), ]); $response = json_decode(curl_exec($ch), true); echo $response['id']; // msg_01J9…
Ruby
require 'net/http' require 'json' uri = URI('https://app.convoai.cloud/api/v1/agents/ag_01J8X…/messages/') req = Net::HTTP::Post.new(uri, { 'Authorization' => 'Bearer ck_live_…', 'Content-Type' => 'application/json', }) req.body = { to: '+15551234567', type: 'text', text: 'Hello from Ruby!' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) } puts JSON.parse(res.body)['id'] # msg_01J9…
Go
package main import ( "bytes"; "encoding/json"; "fmt"; "net/http" ) func main() { body, _ := json.Marshal(map[string]string{ "to": "+15551234567", "type": "text", "text": "Hello from Go!", }) req, _ := http.NewRequest("POST", "https://app.convoai.cloud/api/v1/agents/ag_01J8X…/messages/", bytes.NewBuffer(body)) req.Header.Set("Authorization", "Bearer ck_live_…") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) fmt.Println(result["id"]) // msg_01J9… }