canonical: https://jentic.com/apis/aswat.co/ziwo

# Aswat Ziwo API

Ziwo is a cloud contact-centre platform from Aswat that connects real or virtual agents to phone numbers across more than 150 countries, with prebuilt CRM plugins for Salesforce, HubSpot, Zendesk, and others. The API exposes the full operational surface of a contact centre - authentication and session management, agent and queue administration, call recording and transcription, number provisioning, WhatsApp and SMS channels, IVR configuration, and reporting. It is sized for production telephony deployments rather than light integrations, with hundreds of endpoints covering both admin and supervisor workflows.

## For AI agents

Run a Ziwo cloud contact centre programmatically: provision numbers, manage agents and queues, place or record calls, and pull supervisor reports across voice and messaging channels.

## Scope

Does not handle CRM record management, billing, or video conferencing - use for cloud contact-centre provisioning, call control, and supervisor reporting only.

## Capabilities

- Authenticate agents and supervisors and manage logged-in sessions through `/auth/login`, `/auth/logout`, and `/auth/magicLink`
- Administer agents, queues, and extension maps via the /admin endpoints to model contact-centre routing
- Provision and assign phone numbers, WhatsApp numbers, and call-masking maps to agents and queues
- Place, record, and transcribe calls with the call-control endpoints, then retrieve recordings for QA
- Pull supervisor and reporting data on call volume, agent occupancy, and queue performance
- Manage account recovery, password resets, and magic-link login flows for tenant administrators

## Use cases

### Contact-Centre Provisioning Automation

Operations teams onboarding a new client tenant need to provision numbers, queues, agents, and extension maps consistently. The Ziwo API exposes `/admin/numbers`, `/admin/queues`, and the agent endpoints so a provisioning agent can stand up a working contact centre from a single workflow rather than clicking through the admin UI for each artefact. Typical bulk provisioning for a 50-seat tenant moves from a half-day to minutes.

Example prompt: Provision a new queue named 'Support-EMEA' on the tenant, attach phone number +971-4-XXXX-XXXX, and assign agents 1042 and 1043

### Call Recording and QA Pipelines

Quality assurance teams need to pull call recordings and transcriptions into their review tooling. The Ziwo API exposes recording retrieval keyed by call id, so a QA agent can fetch yesterday's calls for a given queue, push them into the review platform, and tag them with metadata. Combined with reporting endpoints, this drives daily QA sampling without a manual export.

Example prompt: List all calls for queue 'Support-EMEA' on 2026-06-08, fetch the recording URL for each, and submit them to the QA review queue

### WhatsApp and SMS Channel Orchestration

Modern contact centres run voice alongside WhatsApp and SMS. The API exposes WhatsApp number management and messaging endpoints so an agent can route an inbound WhatsApp conversation to the same queue as a voice call, keeping omnichannel reporting consistent. Numbers and queues are linked through extension maps, so reassignments propagate without manual cleanup.

Example prompt: Attach WhatsApp number +971-4-XXXX-XXXX to queue 'Support-EMEA' and verify it appears in the queue's number list

### Supervisor Reporting via Jentic

Through Jentic, an AI agent answering 'how many calls did EMEA take yesterday?' searches by intent and Jentic returns the matching Ziwo reporting operation with its parameters. The Ziwo access_token credential is held in your Jentic One instance, so the agent never sees the secret. This makes contact-centre KPIs answerable directly inside an LLM chat or operations workflow.

Example prompt: Use Jentic to search 'pull queue call volume for yesterday', load the matching Ziwo reporting operation, and execute with queue='Support-EMEA' and date='2026-06-08'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/auth/login` | Log in an agent or supervisor and obtain an access token |
| POST | `/auth/logout` | End the active session |
| GET | `/profile` | Get the logged-in user's profile |
| POST | `/auth/password/reset` | Reset or initiate password reset |
| GET | `/info` | Get system info for the tenant instance |
| POST | `/auth/magicLink/{username}` | Generate a magic-link login token |

## Key resources

- **Auth** — Login, logout, password reset, and magic-link session management
- **Admin** — Administer agents, queues, numbers, and extension maps for a tenant
- **Numbers** — Provision and assign voice numbers and extension maps
- **WhatsApp Numbers** — Manage WhatsApp channel numbers and queue assignments
- **Agents** — Manage agent profiles, status, and queue membership
- **Manage** — Tenant-level configuration and operational controls

## Why Jentic

- **Setup:** Wiring Ziwo by hand means resolving your instance subdomain into the host, handling its access_token header auth, and picking a path from a large contact-centre surface. Through Jentic you install once, import the Ziwo API from the API Directory, store the key once, and your agent calls it while Jentic injects the header.
- **Permission scoping:** Ziwo's auth and profile operations carry their target in the request body or session rather than a resource id in the URL path, so limit the agent to the operations it needs, such as reading a profile or getting instance info. You choose the operations it may call, so a password reset is not included unless you add it.
- **Credential handling:** Your Ziwo access_token is stored once, encrypted, by your own Jentic One instance and injected as the access_token header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'read the current Ziwo profile', and Jentic returns the matching Ziwo operation with its input schema so the agent calls the right endpoint without hunting through the large spec.

## Related APIs

- **Twilio** — General-purpose programmable voice and messaging platform
- **Aircall** — Cloud phone system focused on small to mid-market sales and support teams
- **RingCentral** — Unified communications and contact centre platform

## FAQ

### What authentication does the Ziwo API use?

The Ziwo API uses an API key passed in the access_token header, obtained from POST `/auth/login.` Through Jentic, the credentials are held in the encrypted vault and the access_token header is set at call time, so the secret never appears in the agent's context.

### Can I retrieve call recordings with the Ziwo API?

Yes. Ziwo exposes call-record endpoints under the manage and admin resources, returning the recording metadata and download URLs keyed by call id. A typical QA flow lists calls for a queue and date, then fetches the recording for each.

### What are the rate limits for the Ziwo API?

Ziwo throttles per tenant instance and the spec does not encode a global rate limit. The safest pattern is to back off on HTTP 429 responses, batch reads where the endpoint supports filtering, and avoid polling per agent or per call when a queue-level read is available.

### How do I provision a queue and attach a number through Jentic?

Search Jentic for 'create a queue and attach a number', load the matching POST `/admin/queues` schema, execute it, then load the number-attachment operation under `/admin/numbers` and execute with the queue id and number id. Jentic chains the two calls and injects the access_token for both.

### Can the Ziwo API run WhatsApp alongside voice?

Yes. The WhatsApp Numbers endpoints let you provision WhatsApp channel numbers and attach them to the same queues used for voice, so omnichannel routing and reporting stay consistent across both channels.

### Why is the Ziwo base URL templated?

Ziwo is multi-tenant and the base URL is https://{instance}-api.aswat.co, where {instance} is the tenant subdomain. Substitute the tenant name (for example acme-api.aswat.co) before issuing requests.

### Can I limit what my agent is allowed to do with the Ziwo API?

Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which Ziwo operations and credentials the agent may call. You can allow it just the operations it needs, such as reading a profile through GET /profile or getting instance details through GET /info, and leave out everything else. Since Ziwo's auth and profile operations carry their target in the request body or session rather than a resource id in the path, a sensitive operation like the POST `/auth/password/reset` flow is only available if you explicitly add it.