Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

A DNIs Pool is a rotating pool of Dynamic Number Insertion (DNI) numbers that lets you connect to your Virtual Agent hosted on PolyAI’s infrastructure. This integration passes metadata through PSTN numbers when SIP headers are unavailable.

​
Overview

DNI pooling lets you:
  • Share structured JSON metadata with your agent at the start of a call
  • Retrieve call state information at the end of the conversation
  • Avoid custom SIP header requirements
This is useful when:
  • You’re using PSTN, which does not support sharing metadata
  • You’re using SIP installations that do not support custom SIP headers
A typical use case is sending a shared ID (or other metadata) at call start, and using it later to retrieve handoff details, such as whether the call completed successfully or needs escalation to a human agent.

​
Requirements

To set up the DNIs Pool integration, you’ll need the following from your PolyAI contact:
  • API token for the Reserve DNI endpoint
  • API token for the Get Handoff endpoint
  • Your account_id and project_id
  • Agree with your PolyAI contact on the attributes the Agent will need to extract

​
Integration Runtime

The integration involves two main API endpoints: DNIs Pooling Integration

​
Call flow

The integration flow works as follows:
  1. Client sends project-specific attributes to the Reserve DNI endpoint. An example payload would look like this:
{
    "attributes": {
        "shared_id": "1234567",
        "ani": "+44123456789"
    }
}
  1. PolyAI stores the attributes and returns a reserved DNI (e.g., +12345).
  2. Client initiates a call to the DNI.
  3. PolyAI looks up the attributes for that DNI.
  4. Attributes are forwarded to the Virtual Agent based on your API Key.
  5. The Virtual Agent handles the conversation and stores any agreed data (e.g., handoff status).
  6. The call ends, and PolyAI sends a SIP BYE message.
  7. Client queries the Get Handoff endpoint to retrieve the call outcome. An example response will look like this - note that the shared_id is the same ID you would have sent above:
{
    "data": {
        "handoff_to": "default_queue",
        "handoff_reason": "test_reason"
    },
    "id": "POLYAI_CALL_SID",
    "shared_id": "1234567"
}
  1. If a handoff state is present, the Client can transfer the call to a human agent; otherwise, the call is considered complete.

​
Agent setup

For the integration to work, your agent needs to:
  • Store the attributes you are sending through the Reserve DNI API
  • Save the handoff info into state to have the Get Handoff API expose them when invoked

​
Store attributes

Attributes received from the API can only be accessed in the start_function. Not doing it here would mean losing them for all the conversations, making it impossible for the integration to work. In your start_function, attributes are stored in the integration_attributes field as a dictionary. Retrieve them like this (assuming the attributes sent are the ones in the example above): 
#### anywhere in start_function ####

# Retrieve DNIs Pooling Attributes
shared_id = conv.integration_attributes.get("shared_id")
ani = conv.integration_attributes.get("ani")
if not (shared_id or ani):
  # In case no attributes are received, make sure to handoff to a default queue 
  # on your side if you can't handle the call without the data
  conv.state.handoff_to = "DEFAULT_QUEUE"

print(f"shared_id: {shared_id}, ani: {ani}")  # you can optionally print the attributes

# Store them in the state to use them later in the conversation
conv.state.shared_id = shared_id
conv.state.ani = ani
You can then use those attributes in other functions, in the Managed Topics or elsewhere in your Agent. This will be useful to customize your Agent behavior, or use those attributes in other API calls to your infrastructure for example.

​
Save handoff info

The conversation will always end with this integration. Handoff information must be prepared to be exposed by the Handoff API. The Handoff API can be configured to expose all the state variables you desire. The most useful variables are often:
  • conv.state.handoff_reason - the reason for handoff
  • conv.state.handoff_to - the destination for the call
As long as you store your desired values in state variables, the Handoff API will expose them (if configured to do so). Configuration is handled by your PolyAI contact. Send them all the variables you want to expose, and they will set up the Handoff API accordingly.

​
Pool size

It’s important to make sure that every customer hitting your solution gets to PolyAI. In a DNIs Pooling integration, the pool size is fundamental, as it will dictate how many concurrent calls you will be able to handle. As a rule of thumb, the pool size should be set to at least the maximum number of concurrent calls you expect to handle at peak times to avoid disruptions to your service. The pool size can be controlled by your PolyAI contact, so you can simply share with them the max number of concurrent calls you expect at peak times.

​
Fallback handling

If no DNI is available for your call, the Reserve DNI API returns a 404 status code. Set up your telephony system to handle this case by routing calls to a fallback queue. PolyAI monitors pool utilization per project and will be notified automatically, enabling prompt action to extend the pool size.
Last modified on April 20, 2026