{"article":{"id":5340756791187,"url":"https://playvox.zendesk.com/api/v2/help_center/en-us/articles/5340756791187.json","html_url":"https://help.playvox.com/hc/en-us/articles/5340756791187-Playvox-API-Integration-for-External-Systems","author_id":1510386337822,"comments_disabled":true,"draft":false,"promoted":false,"position":1,"vote_sum":-1,"vote_count":1,"section_id":11105849447443,"created_at":"2022-04-07T00:44:04Z","updated_at":"2025-07-09T05:21:20Z","name":"Playvox API Integration for External Systems","title":"Playvox API Integration for External Systems","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2022-11-10T18:06:40Z","user_segment_id":null,"permission_group_id":18273270434707,"content_tag_ids":[],"label_names":["api","external","integration","delete","create","add","update","metadata"],"body":"
\n
\n
\n
\n
\n
\n
\n
\n
\n

Create an Integration with Playvox API

\n
\n
\n
\n
\n

There are four steps you need to perform to move data from your systems to Playvox:

\n
    \n
  1. \n

    Create the integration

    \n
    2. \n
  2. \n

    Define the metadata for your integration

    \n
    3. \n
  3. \n

    Send your data to Playvox

    \n
    4. \n
  4. \n

    Add comments to the interactions data you’ve sent to Playvox

    \n
    5. \n
\n

The following sections will cover each of these steps in greater detail.

\n

Step 1: Create the Integration

\n

The first thing you need to do is to create the integration, which is essentially a container within Playvox that will hold all of your metadata, interactions, conversations, and so on. It is used by Playvox to “tag” the information you bring in so that it can be handled and displayed appropriately in the user interfaces.

\n

 

\n

If you are logged in to Playvox, you can go to Settings > Integrations to see a full list of the integrations available for your account.

\n
\"Quality_-_Integrations.png\"
\n

This list will include the default integrations that ship with Playvox, as well as any custom integrations you create.

\n

Use the Create endpoint of the Custom Integrations API to create a new integration. You will need to provide the following information to the API endpoint:

\n
    \n
  • \n

    A name for the integration

    \n
    • \n
  • \n

    A brief description for the integration

    \n
    • \n
  • \n

    Some basic settings -- at this time, Playvox asks only for a data_storage_minutes value, which is the maximum number of minutes you want Playvox to store your information (you can set at max 129600 minutes, representing 90 days of data storage)

    \n
    • \n
\n

Playvox will create your integration, and in the response indicating success, there is a field called _id. This is the unique ID for your integration.

\n

When using the Custom Integrations API, you can identify a specific integration using its unique ID. If you aren’t sure what the ID is for a specific integration, you can get a full list of all integrations associated with your account via the API. Once you have the unique ID in hand, you can use the ID to identify integrations you want to update or delete.

\n

 

\n

Relevant Endpoints

\n\n

 

\n

Step 2: Create the Metadata

\n

Once you have created your integration, you will need to define the metadata for your integration. The metadata helps Playvox categorize your data and understand the acceptable values for specific fields. More specifically, your metadata is used by Playvox as the set of criteria to filter and refine the interactions to audit in the user interface.

\n

You can create individual metadata fields by providing the following information to the Add Metadata endpoint:

\n
\n

The following is a sample JSON object that contains the information required by Playvox when creating a new metadata property:

\n
\n

As an example, you can see in the screenshot below how the Quick Filter uses metadata to look for specific interactions:

\n
\"Quick_Filter_1.png\"
\n

Filtering based on Reply Time

\n

 

\n
\"Quick_Filter_2.png\"
\n

Filtering based on Description (note the difference in operators available)

\n

 

\n

Reply time is an example of a metadata property, and based on the property’s type, Playvox knows what operations are allowed on the property values (e.g., datetime values can be compared). 

\n

We recommend doing a full schema of the metadata for your custom system ahead of working with the Playvox API to create your integration so that you know ahead of time the properties and the values you need to input. The following is a simple example of how you could do this:

\n

You must create at least one datetime field (e.g., solved-date or similar). Note, however, that the following values are reserved by Playvox and cannot be used as names for the datetime value(s) you create: created_at, updated_at.

\n
\n
 
\n

Relevant Endpoints

\n\n

 

\n

Step 3: Send Interactions Data to Playvox

\n

Once you’ve created an integration and defined your metadata, you can send the data from your system to Playvox. When sending in your data, Playvox distinguishes between the interactions themselves and the comments on those interactions. In this step, we will focus on the former.

\n

In the Playvox user interface, you can find your interactions listed under Quality > Interactions:

\n
\"Interactions.png\"
\n

Each row represents one interaction. Notice the high-level information that is displayed for each interaction, including the date, its status (e.g., Taken). All of these pieces of information are entered into Playvox as metadata.

\n

Relevant Endpoints

\n\n

Step 4: Send Interactions’ Comments Data to Playvox

\n

Once you’ve sent the interactions data to Playvox, you will need to create the conversations that occur regarding that interaction. Playvox, with the necessary information, will associate the conversation with the appropriate interaction. In the following screenshot, you can see all of the Comments associated with the highlighted interaction on the left:

\n
\"Interactionscomments.png\"
\n

In addition to sending the comments, you will provide as much information about the comment itself as you’d life. For example, our sample comments above include information about the name of the commenter, their email address, and the date/time of the comment.

\n

To send a new comment to Playvox, you can use the Interactions Comment - Create endpoint and provide the following information:

\n
\n
 
\n

Relevant Endpoints

\n\n

Bulk Operations

\n

You can use the bulk API to import interactions in batch from your systems into Playvox. This is designed for high demand operations.
The endpoint accepts an array of up to 100 interactions objects then it will
returns a job JSON object and queuest a background job to do the work. Use the load one Job API endpoint to check for the job status.

\n

Relevant Endpoints

\n\n

Learn how to send audio, video or different types of files in your API Integration for external systems.

\n
\n
\n
\n
\n
\n
\n
","user_segment_ids":[]}}