API & Integrations.
1) API overview
Thunaivi API allows secure integration with CRM, helpdesk, ticketing, billing, and custom backend systems for support
automation workflows.
2) Base URL and auth
- Base URL: https://app.thunaivi.io/api/v1
- Auth header: Authorization: Bearer <API_KEY>
- Content type: application/json
Use server-to-server only. Never expose API keys in frontend.
3) API key lifecycle
- Generate key from client/admin portal
- Show full secret once
- Store only hashed secret in backend
- Rotate keys regularly
- Revoke immediately if compromised
4) Required key controls
- Scope-based access
- IP allowlist (optional but recommended)
- Per-key rate limit
- Expiry date support
- Key status (active / revoked)
5) Common integration use cases
- Create ticket from customer chat
- Sync CRM contact/customer data
- Push conversation updates to external systems
- Trigger workflows from webhook events
- Pull analytics into BI dashboards
6) CRM ticket sync flow (recommended)
1. Customer message enters Thunaivi
2. Intent/rule decides external sync
3. API call creates/updates CRM ticket
4. Ticket ID stored in conversation metadata
5. Status updates are synced both ways
7) Webhook events
Useful events:
- conversation.created
- message.created
- conversation.assigned
- conversation.resolved
Always validate webhook signature before processing.
8) Retry + idempotency
For safe integrations:
- Use idempotency key for create calls
- Retry transient failures with backoff
- Log request_id for every failed call
- Make consumers retry-safe
9) Error handling model
Expect:
- 401 invalid/missing token
- 403 scope/permission denied
- 429 rate limit exceeded
- 422 validation error
- 500 temporary server issue
Handle each with clear retry/escalation logic.
10) Integration security checklist
- Keep API keys in server env/secret manager
- Rotate keys every 60–90 days
- Restrict by scope + IP
- Store minimal PII
- Audit integration logs regularly
- Alert on abnormal usage spikes
11) Integration readiness checklist
- Sandbox test done
- Auth validated
- Rate-limit handling implemented
- Webhook signature validation done
- Monitoring + alerts enabled
- Rollback plan ready
12) Go-live best practices
- Start with one integration path first
- Monitor for 48 hours before scaling
- Track failure ratio and latency
- Document ownership for integration incidents
