Contact Center

• OpenAPI Version: 3.1.1
• API Version: 2

The Contact Center APIs allow developers to interface with Contact Center features programmatically.

Servers

• URL: https://api.zoom.us/v2

Operations

List SMS logs

• Method: GET
• Path: /accounts/{accountId}/contact_center/sms
• Tags: Logs

Returns a list of SMS engagement logs. Engagement data are available via API once they are completed.

Scopes: contact_center_sms:master

Granular Scopes: contact_center:read:sms_log:master

Rate Limit Label: HEAVY

Responses

Status: 200 **HTTP Status Code:** `200` Variables list returned

Content-Type: application/json

• from

  string, format: date-time — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'`, or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.

• next_page_token

  string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.

• page_size

  integer, default: 10 — The number of records returned in a single API call.

• sms

  array — Information about the SMS.

  Items:

  • agents

    array — Information about the engagement's agents.

    Items:

    • display_name

      string — The agent's name.

    • user_id

      string — The agent's ID.

  • consumer_display_name

    string — The consumer's name.

  • consumer_number

    string — The consumer's phone number.

  • contact_center_number

    string — The agent's number. An agent used a flow or queue number and did not really have its own number.

  • country_name

    string — The country name.

  • direction

    string, possible values: "inbound", "outbound" — The engagement's direction. `inbound` | `outbound`.

  • end_time

    string, format: date-time — The date and time when the engagement ended in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.

  • engagement_id

    string — The engagement's ID

  • queues

    array — Information about the engagement's queues.

    Items:

    • cc_queue_id

      string — The Contact Center queue's ID.

    • queue_id

      string — The queue's ID.

    • queue_name

      string — The queue's name.

  • sms_types

    array — The SMS's type.

    Items:

    string, possible values: "sms", "mms"

  • start_time

    string, format: date-time — The date and time when the engagement started in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.

  • total_received_files

    integer, format: int64 — The total number of received files.

  • total_received_messages

    integer, format: int64 — The total number of received messages.

  • total_sent_files

    integer, format: int64 — The total number of sent files.

  • total_sent_messages

    integer, format: int64 — The total number of sent messages.

• to

  string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.

• total_records

  integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "from": "2023-01-01T08:00:00Z",
  "to": "2023-01-01T09:00:00Z",
  "sms": [
    {
      "direction": "inbound",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "contact_center_number": "+18108001001",
      "start_time": "2023-01-01T08:00:00Z",
      "end_time": "2023-01-01T09:00:00Z",
      "consumer_number": "+12059300920",
      "consumer_display_name": "Tester",
      "queues": [
        {
          "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
          "queue_name": "agentQueue"
        }
      ],
      "agents": [
        {
          "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
          "display_name": "Jilly"
        }
      ],
      "country_name": "China",
      "sms_types": [
        "sms"
      ],
      "total_sent_messages": 0,
      "total_received_messages": 0,
      "total_sent_files": 0,
      "total_received_files": 0
    }
  ]
}

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2901` <br> Engagement does not exist: $engagementId. <br> **Error Code:** `1001` <br> User does not exist: $userId. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List voice call logs

• Method: GET
• Path: /accounts/{accountId}/contact_center/voice_calls
• Tags: Logs

Return a list of voice call engagement logs. Engagement data is available via API once it is completed. Note These fields - agents.user_ip_address, agents.user_device_mac_address, agents.user_registered_sip_zone, agents.sip_zone_ip_address, sbcInfos.session_border_controller_name, sbcInfos.session_border_controller_ip_address, sbcInfos.consumer_zoom_trunk_name and sbcInfos.consumer_sbc_ip_address - are only available to accounts which have enabled an internal flag to return these additional fields. To enable the feature flag, contact Zoom Support.

Scopes: contact_center_voice_call:master

Granular Scopes: contact_center:read:voice_call_log:master

Rate Limit Label: HEAVY

Responses

Status: 200 **HTTP Status Code:** `200` Variables list returned.

Content-Type: application/json

• from

  string, format: date-time — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.

• next_page_token

  string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.

• page_size

  integer, default: 10 — The number of records returned within a single API call.

• to

  string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.

• total_records

  integer — The total number of all the records available across pages.

• voice_calls

  array — Information about the voice call.

  Items:

  • agents

    array — Information about the engagement's agents.

    Items:

    • display_name

      string — The agent's name.

    • sip_zone_ip_address

      string, format: ipv4 — The SIP zome's IP address.

    • team_ids

      array — The agent's team IDs

      Items:

      string — agent team ID list

    • team_names

      array — The agent's team names.

      Items:

      string — agent team name list.

    • user_device_mac_address

      string — MAC address of the agent's device.

    • user_email

      string — The agent's email.

    • user_id

      string — The agent's ID.

    • user_ip_address

      string, format: ipv4 — IP address of the agent's device.

    • user_region

      string — The agent's region name

    • user_registered_sip_zone

      string — The SIP zone where the agent registered.

  • call_legs

    array — The direction of the engagement call leg. `inbound` | `outbound`.

    Items:

    string, possible values: "inbound", "outbound"

  • callee_number

    string — The callee's phone number.

  • callee_number_type

    string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The callee's number type.

  • caller_id

    string — The caller's number.

  • caller_number

    string — The caller's phone number.

  • caller_number_type

    string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The caller's number type.

  • calling_party

    string, possible values: "consumer", "agent" — The calling's party.

  • charge

    string — The bill's charge.

  • charge_type

    string, possible values: "per_minute" — The charge type.

  • consumer_display_name

    string — The consumer's name.

  • consumer_number

    string — The consumer's phone number.

  • country_name

    string — The country name.

  • direction

    string, possible values: "inbound", "outbound" — The engagement's direction.

  • distributions

    array — The engagement's distribution.

    Items:

    string, possible values: "acd", "non_acd"

  • end_time

    string — The date and time when the engagement ended, in `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format. The timezone offset is derived from the `from` input parameter if it includes a timezone offset (e.g., `-08:00`), otherwise it defaults to `+00:00` (UTC).

  • engagement_id

    string — The engagement's ID

  • flows

    array — Information about the engagement's flows.

    Items:

    • flow_id

      string — The flow's ID.

    • flow_name

      string — The flow's name.

  • inbox

    boolean — Flag to determine whether a message is in the box.

  • monitored

    boolean — Flag to determine whether to monitored.

  • queues

    array — Information about the engagement's queues.

    Items:

    • cc_queue_id

      string — The Contact Center queue's ID.

    • queue_id

      string — The queue's ID.

    • queue_name

      string — The queue's name.

  • rates

    array — The price for each sent message.

    Items:

    string

  • recorded

    boolean — Flag to determine whether to recorded.

  • result

    string, possible values: "completed", "short_abandoned", "long_abandoned", "hold_abandoned", "long_calls", "short_calls", "hang_up_calls", "overflowed_to_disconnect", "overflowed_to_inbox", "overflowed", "abandon_quit", "auto_closed", "contained", "missed", "declined", "callback_abandoned_by_consumer" — The engagement's results.

  • session_border_controller_list

    array — Information about the session border controllers (SBCs) involved in the call.

    Items:

    • consumer_sbc_ip_address

      string — The customer's SBC IP address.

    • consumer_zoom_trunk_name

      string — The name of the trunk between the customer SBC and Zoom SBC.

    • session_border_controller_ip_address

      string — The SBC's IP address.

    • session_border_controller_name

      string — The session border controller's name.

  • start_time

    string — The date and time when the engagement started in `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format. The timezone offset matches the offset provided in the `from` input parameter, or defaults to UTC (+00:00) if no offset was provided.

  • sub_types

    array — Specifies the detailed call leg type, such as a transfer or conference call.

    Items:

    string, possible values: "external_warm_conference_call", "external_direct_conference_call", "external_warm_transfer_call", "external_direct_transfer_call", "internal_warm_conference_call", "internal_direct_conference_call", "internal_warm_transfer_call", "internal_direct_transfer_call", "flow_initiated_outgoing_call"

  • total_duration

    integer, format: int64 — The engagement's total duration, in seconds.

  • types

    array — The call's type.

    Items:

    string, possible values: "external_call", "external_conference_call", "external_callback_call", "internal_call", "internal_conference_call", "internal_callback_call"

  • voice_call_details

    array — All related call logs.

    Items:

    • agents

      array — Information about the engagement's agents.

      Items:

      • display_name

        string — The agent's name.

      • sip_zone_ip_address

        string, format: ipv4 — The SIP zone's IP address.

      • team_ids

        array — The agent's team IDs

        Items:

        string — Agent team ID list.

      • team_names

        array — The agent's team names.

        Items:

        string — Agent team name list.

      • user_device_mac_address

        string — The agent's device's MAC address.

      • user_email

        string — The agent's email.

      • user_id

        string — The agent's ID.

      • user_ip_address

        string, format: ipv4 — The agent's device's IP address.

      • user_region

        string — The agent's region name.

      • user_registered_sip_zone

        string — The SIP zone where the agent registered.

    • call_leg

      string, possible values: "inbound", "outbound" — The direction of the engagement call log.

    • callee_number

      string — The callee's phone number.

    • callee_number_type

      string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The callee's number type.

    • caller_id

      string — The caller's number.

    • caller_number

      string — The caller's phone number.

    • caller_number_type

      string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The caller's number type.

    • calling_party

      string, possible values: "consumer", "agent" — The calling's party.

    • charge

      string — The bill's charge.

    • charge_type

      string, possible values: "per_minute" — The charge type.

    • consumer_display_name

      string — The consumer's name.

    • consumer_number

      string — The consumer's phone number.

    • country_name

      string — The country name.

    • distribution

      string, possible values: "acd", "non_acd" — The call log's distribution.

    • end_time

      string — The date and time when the call ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.

    • engagement_id

      string — The engagement's ID.

    • flow

      object — Information about the flow.

      • flow_id

        string — The flow's ID.

      • flow_name

        string — The flow's name.

    • inbox

      boolean — Whether a message is in the box.

    • monitored

      boolean — Whether to monitor.

    • queue

      object — Information about the queue.

      • cc_queue_id

        string — The Contact Center queue's ID.

      • queue_name

        string — The queue's name.

    • rate

      string — The price for sent message.

    • recorded

      boolean — Whether to record.

    • result

      string, possible values: "completed", "short_abandoned", "long_abandoned", "hold_abandoned", "long_calls", "short_calls", "hang_up_calls", "overflowed_to_disconnect", "overflowed_to_inbox", "overflowed", "abandon_quit", "auto_closed", "contained", "missed", "declined", "callback_abandoned_by_consumer" — The engagement's results.

    • start_time

      string — The date and time when the call started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.

    • total_duration

      integer, format: int64 — The call log's total duration, in seconds.

    • type

      string, possible values: "external_call", "external_conference_call", "external_callback_call", "internal_call", "internal_conference_call", "internal_callback_call" — The call's type.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "from": "2023-01-01T08:00:00Z",
  "to": "2023-01-01T09:00:00Z",
  "voice_calls": [
    {
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "direction": "inbound",
      "call_legs": [
        "inbound"
      ],
      "distributions": [
        "acd"
      ],
      "types": [
        "external_call"
      ],
      "sub_types": [
        "external_direct_transfer_call"
      ],
      "caller_number": "+18108001001",
      "caller_number_type": "toll_free_number",
      "callee_number": "+12055437350",
      "callee_number_type": "toll_free_number",
      "start_time": "2023-01-01T00:00:00-08:00",
      "end_time": "2023-01-01T01:00:00-08:00",
      "total_duration": 10,
      "consumer_number": "+12059300920",
      "consumer_display_name": "Tester",
      "queues": [
        {
          "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
          "queue_name": "agentQueue"
        }
      ],
      "agents": [
        {
          "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
          "display_name": "Jilly",
          "user_email": "jakie@zoom.us",
          "user_ip_address": "38.145.73.4",
          "user_device_mac_address": "05:FA:15:25:EE:FF",
          "user_registered_sip_zone": "ams1sbc",
          "sip_zone_ip_address": "38.145.73.4",
          "user_region": "Main Region",
          "team_ids": [
            "[\"3XilEfOvQEKRIWMWhX1jDg\"]"
          ],
          "team_names": [
            "[\"My team\"]"
          ]
        }
      ],
      "flows": [
        {
          "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "flow_name": "Demo"
        }
      ],
      "country_name": "China",
      "recorded": false,
      "monitored": false,
      "inbox": false,
      "result": "completed",
      "caller_id": "+12058945728",
      "calling_party": "consumer",
      "charge": "$0.019",
      "rates": [
        "$0.019"
      ],
      "charge_type": "per_minute",
      "session_border_controller_list": [
        {
          "session_border_controller_name": "ams1sbc",
          "session_border_controller_ip_address": "38.145.73.20",
          "consumer_zoom_trunk_name": "C10010142296A06",
          "consumer_sbc_ip_address": "39.15.60.145"
        }
      ],
      "voice_call_details": [
        {
          "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
          "call_leg": "inbound",
          "distribution": "acd",
          "type": "external_call",
          "caller_number": "+18108001001",
          "caller_number_type": "toll_free_number",
          "callee_number": "+12055437350",
          "callee_number_type": "toll_free_number",
          "start_time": "2023-01-01T00:00:00-08:00",
          "end_time": "2023-01-01T01:00:00-08:00",
          "total_duration": 10,
          "consumer_number": "+12059300920",
          "consumer_display_name": "Tester",
          "queue": {
            "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
            "queue_name": "agentQueue"
          },
          "agents": [
            {
              "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
              "display_name": "Jilly",
              "user_email": "jakie@zoom.us",
              "user_ip_address": "38.145.73.4",
              "user_device_mac_address": "05:FA:15:25:EE:FF",
              "user_registered_sip_zone": "ams1sbc",
              "sip_zone_ip_address": "38.145.73.4",
              "user_region": "Main Region",
              "team_ids": [
                "3XilEfOvQEKRIWMWhX1jDg"
              ],
              "team_names": [
                "My team"
              ]
            }
          ],
          "flow": {
            "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
            "flow_name": "Demo"
          },
          "country_name": "China",
          "recorded": false,
          "monitored": false,
          "inbox": false,
          "result": "completed",
          "caller_id": "+12058945728",
          "calling_party": "consumer",
          "charge": "$0.019",
          "rate": "$0.019",
          "charge_type": "per_minute"
        }
      ]
    }
  ]
}

Status: 400 **HTTP Status Code:** `400` <br> Bad Request **Error Code:** `300` <br> The time and date must be in `yyyy-mm-dd`` or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. <br> **Error Code:** `300` <br> The requested report exceeds the 1-month limit. <br> **Error Code:** `300` <br> Invalid field. <br>

Status: 401 **HTTP Status Code:** `401` <br> Unauthorized

Status: 403 **HTTP Status Code:** `403` <br> Forbidden

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `1001` <br> User does not exist: {userId}. <br> **Error Code:** `1201` <br> Queue does not exist: {queueId}. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).