Cisco CVP APIs for Individual Calls in Queue

May 28, 2025 in Wallboard
Cisco CVP APIs for Individual Calls in Queue

Comstice Wallboard helps to monitor individual calls waiting in the queue real-time including the calling number, called number, queue name and the duration.

For this, you will create a simple CVP VXML script that uses one of the REST APIs below and place it after the queue selection in the Cisco ICM Script.

1. Report New Incoming Call in Queue

This REST API reports when a call is enqueued, updated (e.g., position/EWT change), dequeued, or abandoned.

  • URL: https://comstice.yourdomain.com/api/v1/cvp/new-queue-call
  • Method: POST
  • Content-Type: application/json; charset=utf-8
  • Auth: Authorization: Bearer Token
  • Idempotency: Idempotency-Key: uid (so CVP retries don’t double-count)

API Request Body (JSON)


{
  "event_type": "enqueued", 
  "event_time": "2025-09-17T10:33:12.345Z",
  "cvp_call_id": "6d2f0a9b-7b64-4b0a-9a9a-218e3f1d9f20",
  "icm_router_call_key": 123456789,
  "icm_router_call_key_day": 20250917,
  "ani": "+34911222333",
  "dnis": "800123456",
  "queue_id": 30123,
  "queue_type": "PrecisionQueue",
  "position_in_queue": 4,
  "estimated_wait_time_seconds": 95,
  "call_start_time": "2025-09-17T10:31:48.102Z",
  "site": "MAD-ClusterA",
  "metadata": {
    "cvp_label": "PQ_Support_ES",
    "ivr_flow": "Main_ES_Prod",
    "tenant": "Comstice"
  }
}
  • event_type: enqueued | updated | dequeued | abandoned
  • cvp_call_id: a stable correlation key for this call in CVP (string)
  • Add whichever correlation keys you can (e.g., icm_router_call_key(_day))
  • Optional real-time extras: position_in_queue, estimated_wait_time_seconds

Responses

200 OK


{ "status": "ok", "tracking_id": "evt_01HXYZ..." }

4xx/5xx error format: application/problem+json


{
  "type": "https://your.api.example.com/problems/validation-error",
  "title": "Invalid request",
  "status": 400,
  "detail": "queue_id must be a number",
  "instance": "evt_01HXYZ..."
}

2. Retrieve all currently waiting calls in queue

This API helps to report all the calls waiting in the queues;

  • URL: https://comstice.yourdomain.com/api/v1/cvp/queue-statusl
  • Method: POST
  • Content-Type: application/json

{
  "generated_at": "2025-09-17T10:34:00Z",
  "queue_id": 30123,
  "queue_type": "PrecisionQueue",
  "calls": [
    {
      "cvp_call_id": "6d2f0a9b-...",
      "ani": "+34911222333",
      "dnis": "800123456",
      "position_in_queue": 4,
      "estimated_wait_time_seconds": 95,
      "call_start_time": "2025-09-17T10:31:48.102Z"
    }
  ]
}

How to call this from CVP Call Studio (VXML app)

Using the Studio HTTP/REST Client element

  1. Add an HTTP/REST element (name may appear as “HTTP Client”, “REST Client”, or similar depending on CVP version).
    • Method: POST
    • URL: https://comstice.yourdomain.com/api/v1/cvp/new-queue-call
    • Connect/Read Timeout: 2000–3000 ms
    • Follow Redirects: Off
  2. Headers
    • Content-Type: application/json; charset=utf-8
    • Authorization: Bearer ${app.authToken}
    • A unique call id: ${session.sessionid} (or a CVP/ICM call key)
  3. Body (JSON)

    Use Studio variable substitution (notation varies slightly by version). Typical variables:

    • ANI: ${session.telephone.ani}
    • DNIS: ${session.telephone.dnis}
    • A unique call id: ${session.sessionid} (or a CVP/ICM call key)

    Example request body template inside the element:

    
        {
            "event_type": "${call.eventType}", 
            "event_time": "${app.utcnow}",
            "cvp_call_id": "${session.sessionid}",
            "icm_router_call_key": ${call.routerCallKey},
            "icm_router_call_key_day": ${call.routerCallKeyDay},
            "ani": "${session.telephone.ani}",
            "dnis": "${session.telephone.dnis}",
            "queue_id": ${call.queueId},
            "queue_type": "${call.queueType}",
            "position_in_queue": ${call.piq},
            "estimated_wait_time_seconds": ${call.ewt},
            "call_start_time": "${call.startTimeIso}",
            "site": "${app.site}",
            "metadata": {
                "cvp_label": "${call.cvpLabel}",
                "ivr_flow": "${app.flowName}",
                "tenant": "${app.tenant}"
            }
        }

Conclusion

Comstice Wallboard helps Cisco UCCE and PCCE contact centers to perform better and handle customer contacts efficienctly. Click here to learn more about Comstice UCCE/PCCE Wallboard and also request a demo for more details.

Success!