API, webhooks, SIP and SDKs
Reference material for teams integrating Ittisal into their own systems. Everything here assumes a tenant API key and the base URL issued with your licence.
Reference index
REST API
Conversations, contacts, queues, agents, flows and reporting. Cursor pagination, ISO-8601 timestamps, tenant scoping enforced server-side. OpenAPI 3.1 document available per deployment.
Webhook specification
Conversation lifecycle, agent state, disposition written and flow error events. Signed with HMAC-SHA256 over the raw body, five-attempt exponential retry, idempotency key on every delivery.
SIP trunking guide
Termination settings for regional carriers, codec preference order, DTMF handling, SRTP configuration and the media path through the recording and recognition forks.
SDK references
TypeScript and Python clients covering the REST surface, webhook signature verification helpers and typed flow variable access.
Core event types
| Event | Fires when | Key payload fields |
|---|---|---|
| conversation.started | A channel hands a conversation to the flow engine | conversation_id, channel, tenant_id, entry_number |
| conversation.transcript | A recognition turn completes on either leg | speaker, text, confidence, dialect, offset_ms |
| conversation.queued | A queue node assigns or parks the conversation | queue_id, skills, language, capacity_cost |
| conversation.assigned | An agent accepts the conversation | agent_id, wait_ms, transcript_url |
| conversation.disposed | A disposition is written | disposition, sentiment, crm_refs, duration_ms |
| flow.error | A node exceeds its timeout or returns an error | node_id, node_type, error, retry_count |
Payload shapes are versioned with the deployment. Breaking changes ship behind a new event version, never in place.
Need the OpenAPI document?
It is issued per deployment with your base URL and enabled node types.