Skip to main content

Panzo CRM

Panzo is a CRM. With this setup, Panzo asks Oktivo to call a lead with your AI agent, and when the call is over Oktivo sends the result (status, duration, summary, transcript, recording link, extracted answers) back to that lead in Panzo.
Quick overview
  • What you need: an Oktivo account with the CRM API and Webhooks features, one Oktivo agent, and a Panzo account with AI Calls enabled.
  • Time to set up: about 30 minutes, plus a test call.
  • Who does what:
    • Oktivo admin: creates the API token, the agent, the analysis schema and the webhook (steps 1 to 5).
    • Panzo admin: enters the token, agent ID and webhook secret in Panzo (step 6).
  • No Panzo tile: Panzo is not listed under Connecter. You connect it with an API token and a webhook, as described below.
Panzo’s own documentation for this is at app.thepanzo.com/developers.

How it works

  1. A lead arrives in Panzo and Panzo sends a call request to Oktivo. Oktivo answers with a call ID (contactUID).
  2. Oktivo calls the lead.
  3. Oktivo sends results to Panzo’s Results Link. Every result carries the same call ID, so Panzo knows which lead it belongs to.

Before you start

  • Your Oktivo plan includes CRM API and Webhooks. If Settings > API Tokens or Connecter > Webhooks is missing from your dashboard, ask Oktivo support to enable them.
  • You have an Oktivo agent that is ready to call (script written and tested).
  • Your Oktivo account has enough credits.
  • You know who the Panzo admin is, and that person can open Panzo’s AI Calls connection settings.
  • You have a safe place to store secrets (a password manager). The API token and the webhook secret are each shown only once.

Set up

1

Create an API token (Oktivo admin)

In the Oktivo dashboard open Settings (bottom of the left menu), then the API Tokens tab, and click Create Token. Give it a name such as panzo and choose an expiry between 1 and 365 days. An account can have at most 5 active tokens.
The token starts with okt_ and is shown only once. Copy it now. Write down the expiry date: on that day Panzo stops being able to place calls until you rotate or replace the token and update Panzo.
More detail: Authentication.
2

Find the Agent ID (Oktivo admin)

Open Agents in the left menu, open the agent that should call Panzo leads, and copy its ID. Panzo sends this value as agentId with every call request.Developers can also list agents:
3

Use Panzo's variables in the agent script (Oktivo admin)

Panzo sends details about the lead with each call. In your agent script, use these names exactly, with double curly braces:Panzo also sends its own lead number as panzo_lead_id. You do not need it in the script, but it comes back in every result under data.dynamicVariables, which helps when you check a call later.
4

Choose the answers to extract (Oktivo admin)

An analysis schema is the list of answers Oktivo should pull out of each conversation, such as budget or preferred callback time. Panzo shows them as data.analysis.Open Analysis Schemas in the left menu, create or choose a schema, and attach it to the agent. A typical schema for property leads:
Add a summary field. Panzo’s summary is taken from your schema’s summary field. If there is none, Oktivo uses its own automatic conversation summary instead. If neither exists, the summary is left out.
5

Create the webhook (Oktivo admin)

Oktivo needs the address Panzo gave you. In Panzo open Control Panel > Connections > AI Calls and copy the Results Link. Copy it exactly; do not retype it.Then in Oktivo:
  1. Open Connecter in the left menu, then the Webhooks tab, and click Add webhook tool.
  2. Events step: tick call.ended, call.analysis_ready and call.completed. Click Next.
  3. Endpoint step: paste the Results Link into Endpoint URL. Add a description such as “Panzo results”.
  4. Agent Filter (optional): leave it as “All agents (default)” or click Customize and pick the agent from step 2. See Webhook Filtering.
  5. Payload Mode: keep Standard.
  6. Delivery format: choose Panzo CRM. This option only appears in Standard mode.
  7. Click Next, then Create.
  8. A Webhook Secret window opens. Click the copy icon, store the secret safely, then click Done.
If Delivery format stays on Standard (default), Panzo cannot read the signature and rejects every delivery with HTTP 401.
Developers can create the same endpoint with the API instead. See Create the webhook with the API.
6

Enter the details in Panzo (Panzo admin)

Send the handoff checklist to the Panzo admin. In Panzo’s AI Calls connection settings they enter the API token, the agent ID, the webhook secret and the variable names.
7

Place a test call

Create a test lead in Panzo with your own phone number and let Panzo place the call. Answer it and talk for a few seconds.Then check three places:
  • Monitor > Logs > Webhook Logs in Oktivo. You should see call.ended first, then call.analysis_ready and call.completed, each with status 200.
  • The lead in Panzo. The call status, summary and transcript should appear.
  • The extracted answers. If callback_time or budget are missing, check the analysis schema.
Do not use Send Test on the last page of the webhook wizard for Panzo. That test request is sent without a signature, because the secret does not exist yet, so Panzo answers 401. This is expected and does not mean your setup is wrong. Use a real test call, or the signed test below.

Check the secret without placing a call

This sends a correctly signed sample result straight to Panzo. Use it to confirm that the Results Link and the secret match. A lead that does not exist in Panzo is fine; Panzo accepts the request and ignores it.

What Panzo sends to place a call

This is the request Panzo makes to Oktivo. A developer can run it to test the API side without Panzo.
A successful answer (HTTP 201) contains the call ID. It comes back as data.contactUID in every webhook for this call:
Phone numbers must be in international format with a leading +. All dynamicVariables values must be text. See Trigger Call for every field and error.

When Oktivo cannot place the call right now

Panzo can add "deferIfUnavailable": true to the request. Oktivo then queues the call (HTTP 202) when the calling window is closed or voice is briefly down, instead of refusing it. Concurrent-call limit. Your account can only run a set number of calls at once. The Oktivo dashboard does not show this number to customers. Ask Oktivo support for the current value, and ask them to raise it if Panzo regularly receives 429.

Avoiding duplicate calls

The call request has no idempotency key. If a request times out, the call may still have been placed, so Panzo should not repeat it blindly. Check first with Get Call Status, or match on panzo_lead_id in the results.

What Oktivo sends back

Oktivo sends one webhook per event. Subscribe to these three:
Subscribe to call.completed. It is the only event that carries the transcript and the recording link. Oktivo has no call.failed event; an unanswered call arrives as call.ended with a status such as not picked.

Example: call.ended

All values are made up.

Example: call.analysis_ready

This event has no callStatus or callDuration; those come with call.ended and call.completed.

Example: call.completed

Which fields appear depends on what exists for that call. For example, recordingUrl is left out when there is no recording, and transcript is left out when nobody spoke.

What Panzo reads

Call status values

Oktivo sends callStatus as it is. These are the values you can see, with a plain meaning. The most reliable way to tell whether the lead answered is callDuration greater than 0. Rarely, callStatus can hold a raw telephone disconnect reason instead. Treat any value not in this table as “check callDuration”. recordingUrl is a private link that stops working 7 days after it was created. Panzo should download or store the recording when it receives it.

Large calls

Panzo accepts results up to 400,000 characters. When a Panzo CRM delivery would be larger than 350,000 characters, Oktivo removes the duplicate full transcription object. The readable transcript list stays.

Signature

Every delivery is signed so Panzo can tell it came from Oktivo. The signature is in the X-Oktivo-Signature header and is made with your webhook secret. Use Panzo CRM. Panzo checks the signature against the exact bytes it receives. Oktivo also sends X-Oktivo-Timestamp in Panzo CRM mode, but it is not part of the signed text. Oktivo never sends an unsigned result.

Retries and failures

  • Oktivo waits up to 10 seconds for an answer.
  • A failed delivery is retried up to 8 more times, after 10 seconds, 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour and 2 hours.
  • After 50 failed deliveries in a row, Oktivo switches the endpoint off automatically. See below to switch it back on.
  • Panzo answers 200 with {"ok":true} when it accepted a result, including for calls it does not know. It answers 401 for a bad signature, 404 for an unknown Results Link, 413 when the body is too large, 422 when data.contactUID is missing, and 429 when more than 3,000 results per hour arrive for one company.
See Webhooks for the full behaviour.

If something goes wrong

FAQ

No. Everything on the Oktivo side is done in the dashboard. A developer is only needed if you want to run the API requests on this page yourself.
Yes. Leave Agent Filter on “All agents”, or pick several. You can also create one webhook per agent, each with its own secret.
Panzo can no longer place calls and gets an authentication error. Rotate the token in Settings > API Tokens, then enter the new token in Panzo. Results for calls already placed keep arriving, because they use the webhook secret, not the token.
Yes. In Connecter > Webhooks open the webhook, go to the Endpoint step, set Delivery format to Panzo CRM, and click Update. Results queued before the change keep the old format. If you do not have the secret any more, use Regenerate Secret and give Panzo the new one. The old secret stops working immediately.
Enter the new secret in Panzo straight away. Until you do, Panzo rejects results with 401, and Oktivo retries them.
Customers cannot see it in the dashboard. Ask Oktivo support. Developers can read it with the login token (not the API token) from GET /api/v2/my-concurrency.

Create the webhook with the API

Developers can create the webhook in code instead of the dashboard. This request needs the login token (JWT) of an Oktivo user, not the okt_ API token. See Authentication.
The answer contains the secret once:
See Create Endpoint for all fields.

Using n8n, Zapier or other tools

Panzo is not the only way to use this. The same two building blocks work with any tool that can send and receive web requests, such as n8n or Zapier:
  1. The tool places a call with the Trigger Call request, using an API token.
  2. The tool receives results through a webhook. Create the webhook as above, but keep Delivery format on Standard (default) and use the tool’s webhook URL. The Standard format has its own signature, described in Webhooks.
The CRM Integration guide walks through this with code. Choose the Panzo CRM delivery format only for Panzo.

Handoff checklist for the Panzo admin

Send these to the person who configures Panzo:
  • API token (okt_...) and the date it expires
  • Agent ID
  • Webhook secret (the one shown when the webhook was created)
  • Variable names used in the script: name, first_name, source, area
  • Confirmation that the Results Link in Panzo matches the webhook’s Endpoint URL in Oktivo
  • The Oktivo concurrent-call limit (from Oktivo support)
  • Reminder: on HTTP 429 or 503 from Oktivo, wait and try again with growing delays
  • Reminder: after a timeout, check Get Call Status before placing the call again
  • Reminder: download recordings within 7 days

Connectors Overview

Compare the ways to connect Oktivo

Webhooks

Events, signatures and retries

CRM Integration Guide

Generic CRM setup with code samples

Authentication

Create and manage API tokens