Everything you need to set up, train, and deploy your AI customer engagement agent. Pro plan users can also access the REST API for programmatic control.
When a new lead is captured, Otoq sends a POST request to your configured webhook URL. The payload is signed using HMAC-SHA256 with your webhook secret (sent in the X-Webhook-Signature header).
{
"event": "lead.captured",
"timestamp": "2026-02-15T12:00:00.000Z",
"data": {
"id": "lead-uuid",
"agent_id": "agent-uuid",
"conversation_id": "conv-uuid",
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"company": "Acme Inc",
"source": "chat",
"score": 85,
"created_at": "2026-02-15T12:00:00.000Z"
}
}Headers:
Content-Type: application/jsonX-Webhook-Signature: sha256=... — HMAC-SHA256 of the body using your secretX-Webhook-ID: evt_... — Unique event ID for deduplicationProgrammatically manage your agents, conversations, leads, and analytics. API access requires a Pro or Enterprise plan. Generate API keys in your Dashboard → Settings after signing in.
Feed the Markdown to your AI assistant, or use the OpenAPI spec to auto-generate SDKs with tools like openapi-generator.
All API requests require a Bearer token in the Authorization header.
curl https://getotoq.com/api/v1/agents \ -H "Authorization: Bearer otoq_your_api_key_here"
⚠️ Keep your API keys secret
Never expose API keys in client-side code. Use them only in server-to-server communication.
https://getotoq.com/api/v1
All endpoints return JSON. Errors follow the format: { "error": "code", "message": "description" }
API requests are rate limited to prevent abuse. Current limits:
Rate Limit Headers
Every API response includes standard rate limit headers so you can track your usage:
X-RateLimit-Limit: 100 # Max requests per window X-RateLimit-Remaining: 87 # Requests remaining X-RateLimit-Reset: 1708099200 # Unix timestamp when window resets
429 Too Many Requests
When you exceed the limit, the API returns a 429 status with a Retry-After header:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708099200
{
"error": "rate_limited",
"message": "Too many requests. Please slow down."
}Response:
{ "data": [{ "id": "...", "name": "...", "is_active": true, ... }], "meta": { "total": 3 } }Request Body:
{ "name": "Support Bot", "personality": "friendly", "primary_color": "#6366f1" }Response:
{ "data": { "id": "...", "name": "Support Bot", ... } }Response:
{ "data": { "id": "...", "name": "...", "system_prompt": "...", ... } }Request Body:
{ "name": "Updated Bot", "is_active": false }Response:
{ "data": { "id": "...", "name": "Updated Bot", ... } }Response:
{ "success": true }Request Body:
{ "agent_id": "...", "message": "What are your return policies?", "conversation_id": "..." }Response:
{ "data": { "conversation_id": "...", "response": "Our return policy...", "sources": [...] } }Response:
{ "data": [...], "meta": { "total": 142, "limit": 50, "offset": 0 } }Response:
{ "data": { "id": "...", "status": "active", "messages": [{ "role": "user", "content": "..." }, ...] } }Response:
{ "data": [{ "id": "...", "email": "...", "name": "...", ... }], "meta": { "total": 28 } }Response:
{ "data": { "total_conversations": 142, "total_leads": 28, "sentiment": { "positive": 80, ... } } }| Status | Error Code | Description |
|---|---|---|
| 400 | validation_error | Invalid request body or parameters |
| 401 | unauthorized | Missing, invalid, or expired API key |
| 403 | forbidden | Plan does not include API access |
| 404 | not_found | Resource not found or not owned by you |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | Server error — retry or contact support |
You train it by adding knowledge sources — your website URL, documents, or text content. The AI uses this data to answer customer questions accurately using RAG (retrieval-augmented generation). It will never make up information.
The AI will honestly tell the visitor it doesn't have that information and offer to connect them with a human. You'll receive an email notification when a handoff is requested.
Yes! You can set the agent's personality (professional, friendly, casual, formal), provide custom system instructions, configure language preferences, and set a custom welcome message.
Yes. We use encryption in transit (TLS), row-level security policies in our database, rate limiting, and input sanitization. Your data is never used to train third-party AI models. See our Privacy Policy for full details.
A conversation is a chat session between a visitor and your AI agent. Multiple messages within the same session count as one conversation. Each plan has a monthly conversation limit (50 free, 1K starter, 5K growth, 15K pro).
Yes! Each agent has its own embed code. You can create multiple agents for different websites or use the same agent across multiple pages.
Otoq connects to your Shopify store via OAuth. It reads your product catalog (name, description, price, variants, images) and converts them into knowledge sources so your AI agent can answer product questions.
When a new lead is captured, Otoq sends a POST request to your configured webhook URL with the lead data as JSON. Payloads are signed with HMAC-SHA256 for security. Failed deliveries are retried daily.
Can't find what you're looking for? We're here to help.