OVERVIEW

Welcome to the Vozy API! You can use our API interact with communication workflows.

The Vozy API is organized according to REST principles and provides the following functionalities: - Process conversations through campaigns - Reports and Analytics to retrieve conversation details - Discovery services

Environments

This API is available in 2 environments: production and sandbox, reachable via HTTPS.

Specific details relating to the endpoints will be provided upon account creation.

For HTTPS connections, TLS version 1.2 onwards is required to reach production and sandbox environments.

Versioning

Endpoints of the API are prefixed with a corresponding version number. This documentation describes version 2 of the API. Documentation for version 1 is already deprecated.

This method of versioning provides complete isolation between implementations and ensures that subsequent major changes to the API will not affect existing integrations. No breaking changes will be introduced within a major version.

Whenever possible, Vozy will avoid introducing non-backward compatible changes to the API contract, if required, a new major version of the API will be released, however Vozy reserves the right to make additive changes or any non-breaking changes to our API without releasing a new major version or notifying clients.

Clients should ensure their implementation does not break if new fields or other non-breaking changes are introduced

Non-breaking changes Vozy regularly introduces backwards-compatible changes to our API to provide additional product features and capabilities. Non-breaking changes may be introduced without prior warning to users of the Vozy API. Examples of non-breaking changes would be: - New API endpoints - Additional new optional API request fields/parameters for existing endpoints - Additional new optional HTTP headers in API requests for existing endpoints - Additional new fields in API response for existing endpoints - Additional HTTP headers in API response for existing endpoints - Modification of text field values, for instance in error messages - Introduction of new required fields linked to specific conversation channels - Increasing length of existing text field in API requests

The client implementation should be designed with the above in mind, so that non-breaking changes do not adversely affect the implementation.

Breaking changes A breaking change refers to a change that requires an application update to continue working with the API. Examples of breaking changes would be: - Removing or renaming an API endpoint - Changing the accepted values for an API request fields - Adding new mandatory field to an API request body, outside of information required for processing a transaction - Change in an API response structure (renaming of fields)

Whenever possible, a new major version will be introduced if a breaking change is introduced. In the event that a breaking change is unavoidable and a new major version in not possible (e.g., change in regulation, compliance) Vozy will contact clients in advance to ensure there is sufficient time to update the client’s application.

Headers

The endpoints of the API will respond with various header fields, such as Pagination information. All header fields in both requests and responses are case-insensitive, following the HTTP/1.1 specification (RFC 7230). It is advised not to rely on the case-sensitivity of any header fields.

TOPICS

Authentication

To access the API endpoints, you need to include an API Key in the request header. The API Key should be provided as follows:

x-api-key: YOUR_API_KEY

Replace YOUR_API_KEY with the actual API Key assigned to your agent and communication channel. This can be managed at Vozy web Dashboard.

Please ensure the API Key is kept secure and treated as sensitive information to prevent unauthorized access. and should not be shared publicly. Treat it as a sensitive piece of information to prevent unauthorized access to your account and data.

If the API Key is missing or invalid, the API will respond with a 401 Unauthorized status code, indicating that the request lacks valid authentication credentials.

Pagination

GET /{resource}?page=1&per_page=50 HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1

API resources supporting bulk fetches via "list" API methods will be returned in a paginated fashion.

Input Parameters

Field	Required	Type	Description
`page`	No	Integer	Page number
`per_page`	No	Integer	Number of results per page (default 20, maximum 100)

Output Headers

Field	Description
`X-Total`	Total number of records
`X-Total-Pages`	Total number of pages
`X-Per-Page`	Number of records per page
`X-Page`	Current page number
`X-Next-Page`	Next page number (if any)
`X-Prev-Page`	Previous page number (if any)

Discovery Services

These endpoints are used to provide lists of information to the consumer.

Retrieve agent lists

GET /api/v2/accounts/{vozy_account_id}/agents?page=1&per_page=10 HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": [
        {
            "id": "475bda4f-cccd-4c80-a8d8-161c1d2e2cf5",
            "name": "Sample 1",    
            "description": "Asistente_virtual_sample_1",
            "account_id": "abc1def2ghi3jkl4mno5pqr6stu7vwxz",
            "status": 3,
            "timezone": "America/New_York",
            "created_at": "2021-03-14T18:09:04.708466277Z",
            "updated_at": "2021-03-19T17:52:09.770337341Z",
            "variables": [
                {
                    "created_at": "2021-03-19T17:22:15.950263515Z",
                    "description": "Método de pago",
                    "id": "bfa38346-0ea6-4bea-93cb-37c22090f4ea",
                    "kind": 2,
                    "name": "paymentplace",
                    "type": 1,
                    "updated_at": ""
                },
                {
                    "created_at": "2021-03-19T17:27:07.03812268Z",
                    "description": "Nombre del usuario",
                    "id": "8bd5a08a-3e95-4aaa-8d30-0cc53de0d26b",
                    "kind": 1,
                    "name": "userName",
                    "type": 1,
                    "updated_at": ""
                },
                {
                    "created_at": "2021-03-19T17:39:53.290730164Z",
                    "description": "Tipo de contactibilidad",
                    "id": "372dd5b1-a7cf-4566-8f63-3766429941e1",
                    "kind": 1,
                    "name": "CONTACTABILITY",
                    "type": 1,
                    "updated_at": ""
                },
                {
                    "created_at": "2021-03-19T17:30:35.543610321Z",
                    "description": "Fecha de promesa de pago",
                    "id": "dbaa632c-da8a-417e-b854-dc082ae5db63",
                    "kind": 2,
                    "name": "paymentdate",
                    "type": 1,
                    "updated_at": ""
                }
            ]
        },
        {
            "account_id": "abc1def2ghi3jkl4mno5pqr6stu7vwxz",
            "created_at": "2021-04-26T18:05:27.721149952Z",
            "description": "Agente de transferencia",
            "id": "174e9b9a-851f-4553-b0d1-bdedff7e8ea8",
            "name": "Mega_ultra_transfer_agent",
            "status": 3,
            "timezone": "America/Bogota",
            "updated_at": "2022-11-10T22:04:58.239696025Z",
            "variables": [
               {
                    "created_at": "2021-03-19T17:30:35.543610321Z",
                    "description": "Fecha de promesa de pago",
                    "id": "dbaa632c-da8a-417e-b854-dc082ae5db63",
                    "kind": 2,
                    "name": "paymentdate",
                    "type": 1,
                    "updated_at": ""
                },
                {
                    "created_at": "2021-03-19T17:27:07.231446735Z",
                    "description": "Ciudad de residencia del usuario",
                    "id": "38047571-0ec3-48c4-bcd7-89f441250af9",
                    "kind": 1,
                    "name": "userCity",
                    "type": 1,
                    "updated_at": ""
                },
                {
                    "created_at": "2021-04-26T18:08:57.728399513Z",
                    "description": "",
                    "id": "0672914c-7356-4563-86d3-50b3804284de",
                    "kind": 1,
                    "name": "phone",
                    "order": "9",
                    "type": 1,
                    "updated_at": "2023-01-11T17:24:55.099709488Z"
                }
            ]
        }
    ]
}

The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
vozy_account_id	true	String	Vozy Account Id
page	false	Integer	Page number	Query param
per_page	false	Integer	Number of results per page (default 20, maximum 50)	Query param

Returns

Array of Agents object.

Retrieve agent information by agent id

GET /api/v2/accounts/{vozy_account_id}/agent/{agent_id} HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
        "id": "475bda4f-cccd-4c80-a8d8-161c1d2e2cf5",
        "name": "Sample 1",    
        "description": "Asistente_virtual_sample_1",
        "account_id": "abc1def2ghi3jkl4mno5pqr6stu7vwxz",
        "status": 3,
        "timezone": "America/New_York",
        "created_at": "2021-03-14T18:09:04.708466277Z",
        "updated_at": "2021-03-19T17:52:09.770337341Z",
        "variables": [
            {
                "created_at": "2021-03-19T17:22:15.950263515Z",
                "description": "Método de pago",
                "id": "bfa38346-0ea6-4bea-93cb-37c22090f4ea",
                "kind": 2,
                "name": "paymentplace",
                "type": 1,
                "updated_at": ""
            },
            {
                "created_at": "2021-03-19T17:27:07.03812268Z",
                "description": "Nombre del usuario",
                "id": "8bd5a08a-3e95-4aaa-8d30-0cc53de0d26b",
                "kind": 1,
                "name": "userName",
                "type": 1,
                "updated_at": ""
            },
            {
                "created_at": "2021-03-19T17:39:53.290730164Z",
                "description": "Tipo de contactibilidad",
                "id": "372dd5b1-a7cf-4566-8f63-3766429941e1",
                "kind": 1,
                "name": "CONTACTABILITY",
                "type": 1,
                "updated_at": ""
            },
            {
                "created_at": "2021-03-19T17:30:35.543610321Z",
                "description": "Fecha de promesa de pago",
                "id": "dbaa632c-da8a-417e-b854-dc082ae5db63",
                "kind": 2,
                "name": "paymentdate",
                "type": 1,
                "updated_at": ""
            }
        ]
    }
}

Retrieve information for a given agent. The id of the agent must be supplied replacing {agent_id} in the URI path.

Request parameters

Name	Required	Type	Description	Format
vozy_account_id	true	String	Vozy Account Id
agent_id	true	String	Agent unique identifier	UUID v4

Returns

Agent object.

Get agent variables

GET /api/v2/accounts/{vozy_account_id}/variables HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": [
        {
            "description": "Debt amount",
            "id": "0992e157-80b4-476e-8e7c-4713b8fea054",
            "name": "amount"
        },
        {
            "description": "",
            "id": "a9770c1b-5965-40b1-a903-5638d72b9ed7",
            "name": "dni_number"
        },
        {
            "description": "Contact full name",
            "id": "67c9b866-1ae5-4da6-af9a-f6afbd4ed240",
            "name": "fullname"
        }
    ],
    "error": null
}

The campaigns can be set values from the contacts data to use in conversational flow. This is to retrieve agent's variable in order to help with mapping. The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
vozy_account_id	true	String	Vozy Account Id

Returns

Array of agent variables object.

Field	Type	Description
id	String	Variable identifier
name	String	Variable name
description	String	Variable description

Conversation Services

Create conversation

POST /api/v2/accounts/{vozy_account_id}/conversation HTTP/1.1
x-api-key: YOUR_API_KEY

Request

{
    "numbers_make_calls": ["+573210000001"],
    "timezone": "America/Bogota",
    "conversation_variables": [
        {
            "variable_name": "phone",
            "variable_id": "7f48e14b-ef8d-4eeb-a9ab-cf00c0709850"
        },
        {
            "variable_name": "name",
            "variable_id": "c0550d0a-8a30-47a4-b7e1-3c1815f33872"
        },
        {
            "variable_name": "full_name",
            "variable_id": "b8aba7f2-abbb-463c-9571-46454225c6f5"
        },
        {
            "variable_name": "id_number",
            "variable_id": "bc1fffb6-48a5-400f-b201-cd0a9725c9f1"
        }
    ],
    "contact": {
        "name": "John",
        "full_name": "John Doe",
        "id_number": "99887766",
        "phone": "573210000000"
    },
    "call_group_name": "My group name",
}

200 OK

{
    "data": "Message sent successfully",
    "error": null,
    "message": ""
}

This communication method is suitable when not all contacts are available at the start of the campaign but are acquired progressively through business operations, such as lead qualifications, social network forms, registration forms, etc.

The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
numbers_make_calls	No	Array of string	Used in Voice conversations only. The specific phone numbers from which the end user will receive the conversations.
timezone	Yes	String	The timezone to used in the conversation to calculate available time.	TZ Name
conversation_variables	No	Object	Used for set agent variables (the id) and the contact keys. If the agent no required any value from the contact data can be skipped this field.	Key – value JSON
contact	Yes	Object	This contains contacts data, The keys must be consistent across all contacts, in case of one contacts does not have value for a key, set a empty string.	JSON key-value. Nested or complex structures are not supported. Among all contact properties, *phone* is mandatory and must include the Contact phone number, in the required format.
call_group_name	No	String	A existent contact group in account. If empty, a new Contact group is created for each contact.	Up to 30 characters length

Returns

Conversation created confirmation.

Create campaign

POST /api/v2/accounts/{vozy_account_id}/campaign HTTP/1.1
x-api-key: YOUR_API_KEY

Voice Campaign - Request

{
    "name": "Preventative default - Jan 2023",
    "interval": "01:00:00",
    "retries": 2,
    "timezone": "America/Bogota",
    "map": {
        "ae099c34-9426-44a3-954c-e1ef5df96257": "name",
        "b3271060-c44d-4af1-8cdd-40effdcc0d4a": "phone"
    },
    "scheduled_type": {
        "type": "custom",
        "available_time_from": "08:00:00",
        "available_time_to": "17:59:59"
    },
    "start_date": "2023-01-15 08:00",
    "end_date": "2023-01-15 18:00",
    "phone_fields": [
        "phone"
    ],
    "dynamic_contact_group": false,
    "contact_group": "",
    "campaign_type": 1,
    "automatic_flow_id": "",
    "exclusion_groups": [
      "9e774aac-fa15-4bea-ab46-3abdf66bfc2b",
      "f6f48881-1cf0-4bce-9cc7-610e31af09e8"
    ]

}

201 Created

{
    "data": {
        "id": "e3dbfe5c-43b2-4e29-90e0-8f38b2630cbd",
        "name": "Preventative default - Jan 2023",
        "interval": "01:00:00",
        "retries": 2,
        "timezone": "America/Bogota",
        "start_date": "2023-01-15 08:00:00",
        "end_date": "2023-01-15 18:00:00",
        "map": {
            "c0974e41-772c-475d-881e-9d706be1b421": "name",
            "ce9e1754-b63f-4614-9e73-3540abdce885": "phone"
        },
        "contact_group": "02063b2c-2e05-47b5-a600-b786764f746e",
        "number_calls": [
            "+573590000047"
        ],
        "status": "CAMPAIGN_STATUS_SCHEDULED",
        "scheduled_type": {
            "type": "custom",
            "available_time_from": "08:00:00",
            "available_time_to": "17:59:59"
        },
        "dynamic_contact_group": false,
        "phone_fields": [
            "phone"
        ],
        "interval_phone_fields": "5m",
        "campaign_type": 1,
        "exclusion_groups": null,
        "automatic_flow_id": "",
        "automatic_flow_workflow_id": "",
        "current_automaticflow_node_id": "",
        "parent_campaign_id": ""
    },
    "error": null,
    "message": "created"
}

WhatsApp Campaign - Request

{
    "name": "My WhatsApp Campaign",
    "interval": "",
    "timezone": "America/Bogota",
    "map": {
        "ae099c34-9426-44a3-954c-e1ef5df96257": "name",
        "b3271060-c44d-4af1-8cdd-40effdcc0d4a": "phone"
    },
    "scheduled_type": {
        "type": "custom",
        "available_time_from": "09:00:00",
        "available_time_to": "17:59:59"
    },
    "start_date": "",
    "contact_group": "033ba53f-6c9a-48ca-bc30-b49d0bef4493",
    "dynamic_contact_group": false,
    "campaign_type": 1
}

201 Created

{
    "data": {
        "id": "d7142145-1b06-4f6f-bb76-b1fc689590ac",
        "name": "My WhatsApp Campaign",
        "interval": "",
        "retries": 1,
        "timezone": "America/Bogota",
        "start_date": "2024-03-15 09:00:00",
        "end_date": "2024-03-15 18:00:00",
        "map": {
            "c0974e41-772c-475d-881e-9d706be1b421": "name",
            "ce9e1754-b63f-4614-9e73-3540abdce885": "phone"
        },
        "contact_group": "033ba53f-6c9a-48ca-bc30-b49d0bef4493",
        "number_calls": [
            "+573590000047"
        ],
        "status": "CAMPAIGN_STATUS_SCHEDULED",
        "scheduled_type": {
            "type": "custom",
            "available_time_from": "09:00:00",
            "available_time_to": "17:59:59"
        },
        "dynamic_contact_group": false,
        "phone_fields": [
            "phone"
        ],
        "interval_phone_fields": "",
        "campaign_type": 1,
        "exclusion_groups": null,
        "automatic_flow_id": "",
        "automatic_flow_workflow_id": "",
        "current_automaticflow_node_id": "",
        "parent_campaign_id": ""
    },
    "error": null,
    "message": "created"
}

Creates a campaign in order to determine how Lili will reach out to contacts.

The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
name	Yes	String	The campaign name.	Text between 5 and 23 characters long
interval	Yes	String	Time interval between retries.	HH:MM:SS
number_calls	No	String array	The phone number to make outbound calls	International phone number format
retries	Yes	Integer	Number of retries to make calls to a contact	0
timezone	Yes	String	The timezone to used in the campaign for calculate the available time and the start and finish date	TZ Name.
contact_group	No	String	A existent contact group in account. If empty, automatically the platform creates an empty contact group for add new contacts with another api endpoint.	UUID V4
scheduled_type	Yes	Object	Set the window to make calls.	See Scheduled Types
start_date	No	String	The date time to start the campaign. If empty the campaign starts now.	YYYY-MM-DDHH:MM
end_date	Yes	String	The date time to end the campaign. If empty the campaign ends once all contacts have been processed and retries exhausted.	YYYY-MM-DDHH:MM
map	No	JSON	Used for set the matchbetween the agentvariables (the id) and the contact keys. If the agent no required any value from the contact data can be skipped this field.	Key – value JSON
dynamic_contact_group	Yes	Boolean	Please set to false, only the contacts added before the campaign change to active will be called.	Boolean
phone_fields	No	String array	The keys in the contact data that contain the phonenumber to call. If yourcontact group have this field mapped as "phone", "Phone" you can skip this field, another case, you need to set the key or keys names in the array.	0
interval_phone_fields	No	String	The time to await between a contacts phone. The default value is "5m"
campaign_type	Yes	Integer	The campaign type	See The campaign types
exclusion_groups	No	String array	The ID(s) of the exclusion groups are obtained directly from the Vozy web platform. To find them, simply access an exclusion group and locate the ID in the page URL.	Array of UUID V4
automatic_flow_id	No	String	Unique identifier for an Automated Flow previously defined at Admin Dashboard	UUID V4

Returns

Campaign object.

Retrieve a campaign

GET /api/v2/accounts/{vozy_account_id}/campaign/{campaign_id} HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
        "id": "e3dbfe5c-43b2-4e29-90e0-8f38b2630cbd",
        "name": "Preventative default - Jan 2023",
        "interval": "01:00:00",
        "retries": 2,
        "timezone": "America/Bogota",
        "start_date": "2023-01-15 08:00:00",
        "end_date": "2023-01-15 18:00:00",
        "map": {
            "c0974e41-772c-475d-881e-9d706be1b421": "name",
            "ce9e1754-b63f-4614-9e73-3540abdce885": "phone"
        },
        "contact_group": "02063b2c-2e05-47b5-a600-b786764f746e",
        "number_calls": [
            "+573590000047"
        ],
        "status": "CAMPAIGN_STATUS_SCHEDULED",
        "scheduled_type": {
            "type": "custom",
            "available_time_from": "08:00:00",
            "available_time_to": "17:59:59"
        },
        "dynamic_contact_group": false,
        "phone_fields": [
            "phone"
        ],
        "interval_phone_fields": "5m",
        "campaign_type": 1,
        "exclusion_groups": null,
        "automatic_flow_id": "",
        "automatic_flow_workflow_id": "",
        "current_automaticflow_node_id": "",
        "parent_campaign_id": ""
    },
    "error": null,
    "message": "created"
}

Returns an specific campaign.

The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
campaign_id	Yes	String	Unique campaign ID retrieved in Create Campaign endpoint	UUID V4

Returns

Campaign object.

Change campaign status

PUT /api/v2/accounts/{vozy_account_id}/campaign/{campaign_id}/status HTTP/1.1
x-api-key: YOUR_API_KEY

Request

{
    "status":"CAMPAIGN_STATUS_CANCELED"
}

200 OK

{
    "data": {
        "id": "d7142145-1b06-4f6f-bb76-b1fc689590ac",
        "name": "My WhatsApp Campaign",
        "retries": 1,
        "timezone": "America/Bogota",
        "start_date": "2023-02-15 08:00:00",
        "end_date": "2023-02-15 17:59:59",
        "map": {
            "c0974e41-772c-475d-881e-9d706be1b421": "name",
            "ce9e1754-b63f-4614-9e73-3540abdce885": "phone"
        },
        "contact_group": "02063b2c-2e05-47b5-a600-b786764f746e",
        "number_calls": [
            "+573590000047"
        ],
        "status": "CAMPAIGN_STATUS_CANCELED",
        "scheduled_type": {
            "type": "custom",
            "available_time_from": "08:00:00",
            "available_time_to": "17:59:59"
        },
        "dynamic_contact_group": false,
        "phone_fields": [
            "phone"
        ],
        "interval_phone_fields": "5m",
        "campaign_type": 1,
        "exclusion_groups": null,
        "automatic_flow_id": "",
        "automatic_flow_workflow_id": "",
        "current_automaticflow_node_id": "",
        "parent_campaign_id": ""
    },
    "error": null,
    "message": "created"
}

The campaign automatically changes the status when the conditions set for execution has been completed. However, you can make a request to change the status, for example: to pause or cancel a campaign always the current status be different to CAMPAIGN_STATUS_FINISHED, CAMPAIGN_STATUS_FAILED or CAMPAIGN_STATUS_CANCELED

The You must replace {vozy_account_id} in URI path.

Request parameters

Name	Required	Type	Description	Format
campaign_id	Yes	String	Unique campaign ID retrieved in Create Campaign endpoint	UUID V4
status	Yes	String	The new campaign status to set	See Campaign Status

Returns

Campaign object.

Audience Services

Add Contacts to campaign using JSON structure

PUT /api/v2/accounts/{vozy_account_id}/campaign/{campaign_id}/contact-group/{campaign_contact_group}?format=json HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json

Request

{
    "contacts": [
        {
            "fullName": "John Doe",
            "phone": "573992987654",
            "phone2": "573123547524",
            "amount": 10000,
        },
        {
            "fullName": "Hugo Rodriguez",
            "phone": "573990017654",
            "phone2": "",
            "amount": 50000,
        }
    ]
}

201 Created

{
    "data": {
        "success": true,
        "processed": 2,
        "failed": 1
    },
    "error": null,
    "message": "success"
}

You can add contacts to the campaign contact group from excel, csv and JSON request.

The You must replace {vozy_account_id} in URI path.

From Create Campaign endpoint you can retrieve {campaign_contact_group} value and replace it, as it's mandatory. format query param is also mandatory, and can receive two possible values: json or file

Request parameters

Name	Required	Type	Description	Format
contacts	Yes	JSON array	An array with contacts data, The keys must be consistent across all contacts, in case of one contacts does not have value for a key, set a empty string.	JSON key-value. Nested or complex structures are not supported.

Returns

Contact confirmation object.

Add Contacts to campaign using file

PUT /api/v2/accounts/{vozy_account_id}/campaign/{campaign_id}/contact-group/{campaign_contact_group}?format=file HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data

201 Created

{
    "data": {
        "success": true,
        "processed": 2,
        "failed": 1
    },
    "error": null,
    "message": "success"
}

You can add contacts to the campaign contact group from excel, csv and JSON request.

The You must replace {vozy_account_id} in URI path.

Please make sure Content-Type header is set to multipart/form-data

Request parameters

Name	Required	Type	Description	Format
file	Yes	File	The file to upload and process.	Files with extension xls, xlsx, csv are supported.

Returns

Contact confirmation object.

Retrieve contact group content

GET /api/v2/accounts/{vozy_account_id}/campaign/{campaign_id}/contact-group/{campaign_contact_group}?format=file HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
        "contacts": [
            {
                "id": "1e9eeba5-ef96-43e6-83e2-368c0ad3b1fb",
                "account_id": "e7bea15ae760880704a447ecb0c97b7c",
                "contact_group_id": "02063b2c-2e05-47b5-a600-b786764f746e",
                "created_at": "2023-08-01T22:33:39.720123956Z",
                "updated_at": "",
                "vozy_batch_id": "batch__1690929219698",
                "vozy_error_validation": "",
                "vozy_valid_field": "true",
                "fullName": "John Doe",
                "phone": "573992987654",
                "phone2": "573123547524",
                "amount": 10000
            },
            {
                "id": "1e9eeba5-ef96-43e6-83e2-368c0ad3b1fb",
                "account_id": "e7bea15ae760880704a447ecb0c97b7c",
                "contact_group_id": "02063b2c-2e05-47b5-a600-b786764f746e",
                "created_at": "2023-08-01T22:33:39.720123956Z",
                "updated_at": "",
                "vozy_batch_id": "batch__1690929219698",
                "vozy_error_validation": "",
                "vozy_valid_field": "true",
                "fullName": "Hugo Rodriguez",
                "phone": "573990017654",
                "phone2": "",
                "amount": 50000,
            }
        ],
        "pagination": {
            "limit": "2",
            "page": "1",
            "pages": "29",
            "results": "2",
            "total": "57"
        }
    },
    "error": null,
    "message": "success"
}

This allows to get all contact group items and can be used to validate how each contact has been processed before launching a campaign.

The You must replace {vozy_account_id} in URI path.

From Create Campaign endpoint you can retrieve {campaign_contact_group} value and replace it, as it's mandatory.

Returns

Contact group summary object.

Reporting Services

Retrieve conversation record

GET /api/v2/accounts/{vozy_account_id}/call-record?start_date=1693116000&end_date=1693720799&page=1&per_page=2 HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
        "call_record": [
            {
                "session_id": "sid-659fbb2c-b636-4b29-aaf8-feef6d9ba892-1693260541.248",
                "contact_phone": "+575550000010",
                "call_direction": "OUTBOUND",
                "call_fallback": true,
                "call_id": "659fbb2c-b636-4b29-aaf8-feef6d9ba892",
                "call_transfered": false,
                "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                "campaign_id": "2a39d405-bec4-4a62-8f5b-ffaf5e3272c1",
                "campaign_name": "campaignSuccessUsage",
                "channel_type": "voicebot",
                "attempt_id": "1",
                "billing": "1.73",
                "call_answered": true,
                "call_contacted": true,
                "contact_confirmed": false,
                "contactability_type": "",
                "date": "2023-08-28T22:10:45Z",
                "duration": 104,
                "engagement": false,
                "fallback_type": "FALLBACK",
                "hang_up_cause": "USER_HANGUP",
                "invalid_phone_number": false,
                "is_fallback": true,
                "recall": false,
                "recall_type": "",
                "retention": false,
                "succes": null,
                "success_type": null,
                "transfered": false,
                "variables": [
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "Comentario",
                        "id": "dfd02147-02fa-4b14-b8e2-cfeda2374cbc",
                         "kind": 2,
                        "name": "anycomment_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    },
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "",
                        "id": "8459cc5e-01da-45f5-9ce7-2cb70b16daba",
                        "kind": 2,
                        "name": "recall_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    }
                ],
                "sent_sms_nodes": null,
                "sent_whatsapp_nodes": null
            },
            {
                "session_id": "sid-9516aa54-9b43-48fc-9b99-cf8508869284-1693260287.807",
                "contact_phone": "+575550000011",
                "call_direction": "OUTBOUND",
                "call_fallback": false,
                "call_id": "9516aa54-9b43-48fc-9b99-cf8508869284",
                "call_transfered": false,
                "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                "campaign_id": "3ecf0fb2-3007-4b5c-8f15-9dbcc150f0a8",
                "campaign_name": "campaignSchedule",
                "channel_type": "voicebot",
                "attempt_id": "1",
                "billing": "1.73",
                "call_answered": true,
                "call_contacted": true,
                "contact_confirmed": false,
                "contactability_type": "",
                "date": "2023-08-28T22:06:31Z",
                "duration": 104,
                "engagement": true,
                "fallback_type": "",
                "hang_up_cause": "CALL_ENDED_PROPERLY",
                "invalid_phone_number": false,
                "is_fallback": false,
                "recall": false,
                "recall_type": "",
                "retention": true,
                "status": "",
                "succes": null,
                "success_type": null,
                "transfered": false,
                "variables": [
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "Comentario",
                        "id": "dfd02147-02fa-4b14-b8e2-cfeda2374cbc",
                         "kind": 2,
                        "name": "anycomment_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    },
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "",
                        "id": "8459cc5e-01da-45f5-9ce7-2cb70b16daba",
                        "kind": 2,
                        "name": "recall_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    }
                ],
                "sent_sms_nodes": null,
                "sent_whatsapp_nodes": null
            }
        ]
    }
}

Retrieve all conversations per agent or campaign within a specific date range. start_date and end_date are expressed on UTC Unix Time. Max records returned per time range: 10,000 records.

Request parameters

Name	Type	Required	Type	Description	Format
account_id	Path	Yes	String	Vozy account identifier
filter_type	Path	Yes	String	Filter to be used in query: agent or campaign
filter_id	Path	Yes	String	Agent or campaign identifier	UUID v4
start_date	Query	Yes	Integer	The minimum date time to return results	Unix time
end_date	Query	Yes	Integer	The maximum date time to return results	Unix time
page	Query	No	Integer	See Pagination
per_page	Query	No	Integer	See Pagination

Returns

Conversation record object.

Get analytics and conversation record

GET /api/v2/accounts/{vozy_account_id}/:filter_type/:filter_id/report?start_date=1693116000&end_date=1693720799&page=1&per_page=2&include_call_record=true HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
         "analytics_overview": {
            "average_call_duration_sec": 73,
            "average_interactions": 4.375,
            "confirmed_by_contacted": 0,
            "percentage_contactability": 0.66,
            "percentage_engagement": 0.83,
            "percentage_retention": 1,
            "percentage_success_rate": 0,
            "total_answered": 8,
            "total_call_ended": 8,
            "total_confirmed": 0,
            "total_contactability": 8,
            "total_contacted": 6,
            "total_contacts": 9,
            "total_engaged": 5,
            "total_recall": 0,
            "total_retention": 6,
            "total_success": 0,
            "total_voicemail": 1
        },
        "call_record": [
            {
                "session_id": "sid-659fbb2c-b636-4b29-aaf8-feef6d9ba892-1693260541.248",
                "contact_phone": "+575550000010",
                "call_direction": "OUTBOUND",
                "call_fallback": true,
                "call_id": "659fbb2c-b636-4b29-aaf8-feef6d9ba892",
                "call_transfered": false,
                "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                "campaign_id": "2a39d405-bec4-4a62-8f5b-ffaf5e3272c1",
                "campaign_name": "campaignSuccessUsage",
                "channel_type": "voicebot",
                "attempt_id": "1",
                "billing": "1.73",
                "call_answered": true,
                "call_contacted": true,
                "contact_confirmed": false,
                "contactability_type": "",
                "date": "2023-08-28T22:10:45Z",
                "duration": 104,
                "engagement": false,
                "fallback_type": "FALLBACK",
                "hang_up_cause": "USER_HANGUP",
                "invalid_phone_number": false,
                "is_fallback": true,
                "recall": false,
                "recall_type": "",
                "retention": false,
                "status": "",
                "succes": null,
                "success_type": null,
                "transfered": false,
                "variables": [
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "Comentario",
                        "id": "dfd02147-02fa-4b14-b8e2-cfeda2374cbc",
                         "kind": 2,
                        "name": "anycomment_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    },
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "",
                        "id": "8459cc5e-01da-45f5-9ce7-2cb70b16daba",
                        "kind": 2,
                        "name": "recall_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    }
                ],
                "sent_sms_nodes": null,
                "sent_whatsapp_nodes": null
            },
            {
                "session_id": "sid-9516aa54-9b43-48fc-9b99-cf8508869284-1693260287.807",
                "contact_phone": "+575550000011",
                "call_direction": "OUTBOUND",
                "call_fallback": false,
                "call_id": "9516aa54-9b43-48fc-9b99-cf8508869284",
                "call_transfered": false,
                "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                "campaign_id": "3ecf0fb2-3007-4b5c-8f15-9dbcc150f0a8",
                "campaign_name": "campaignSchedule",
                "channel_type": "voicebot",
                "attempt_id": "1",
                "billing": "1.73",
                "call_answered": true,
                "call_contacted": true,
                "contact_confirmed": false,
                "contactability_type": "",
                "date": "2023-08-28T22:06:31Z",
                "duration": 104,
                "engagement": true,
                "fallback_type": "",
                "hang_up_cause": "CALL_ENDED_PROPERLY",
                "invalid_phone_number": false,
                "is_fallback": false,
                "recall": false,
                "recall_type": "",
                "retention": true,
                "succes": null,
                "success_type": null,
                "transfered": false,
                "variables": [
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "Comentario",
                        "id": "dfd02147-02fa-4b14-b8e2-cfeda2374cbc",
                         "kind": 2,
                        "name": "anycomment_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    },
                    {
                        "agent_id": "361b4663-41c7-4670-b831-4cc4069ec7b3",
                        "created_at": "2023-08-28T22:10:41Z",
                        "description": "",
                        "id": "8459cc5e-01da-45f5-9ce7-2cb70b16daba",
                        "kind": 2,
                        "name": "recall_global",
                        "type": 1,
                        "updated_at": "2023-08-28T22:10:41Z",
                        "value": ""
                    }
                ],
                "sent_sms_nodes": null,
                "sent_whatsapp_nodes": null
            }
        ]
    }
}

Retrieve analytics performance from an specific agent or campaign, based on Contactability, Success, Engagement and Retention metrics. Query can also include conversation record, if required.

Request parameters

Name	Param	Required	Type	Description	Format
account_id	Path	Yes	String	Vozy account identifier
filter_type	Path	Yes	String	Filter to be used in query: agent or campaign
filter_id	Path	Yes	String	Agent or campaign identifier	UUID v4
start_date	Query	Yes	Integer	The minimum date time to return results	Unix time
end_date	Query	Yes	Integer	The maximum date time to return results	Unix time
page	Query	No	Integer	See Pagination
per_page	Query	No	Integer	See Pagination
include_call_record	Query	No	Boolean	Determines if conversation record will be returned or not

Returns

Performance analytics overview object.

Get call recording

GET /api/v2/accounts/:account_id/recordings/:session_id HTTP/1.1
x-api-key: YOUR_API_KEY

200 OK

{
    "data": {
            "audio_url": "https://lili.example.com/422c91c0ecaed4bed4e0/74369389-14fd-4fcb-be1f-416bf42ff7f3/sid-dcfb05ea-e68b-4ac2-b92a-71440e104777-1706904340.039.wav",
            "session_id": "sid-dcfb05ea-e68b-4ac2-b92a-71440e104777-1706904340.039"
        },
    "error": null
}

404 Not Found

{
    "data": null,
    "error": "No audio found"
}

Retrieve audio recording for voice conversations. This API returns a download link with an standard duration of 15 minutes for the client to download the audio. Thus download link can be used once.

Request parameters

Name	Param	Required	Type	Description	Format
account_id	Path	Yes	String	Vozy account identifier
session_id	Path	Yes	String	Session ID

Returns

Conversation audio object.

Name	Type	Description	Format
audio_url	String	Temporal audio link ready to download	HTTP URL
session_id	String	Session ID

Resources

Designed around REST principles, data are passed to and from endpoints of the API as resources. These resources are expressed as objects in JSON, and are described in more detail below.

Pagination object

Represents a pagination summary in order to iterate results through pages

Field	Type	Description
limit	String	Maximum number of objects to be retrieved
page	String	Current page number
pages	String	Total of available pages to get all objects
results	String	Actual page size
total	String	Total objets count

Agent

An agent represents the desired workflow for a conversation

Field	Type	Description
id	String	Agent unique identifier
name	String	Agent name
description	String	Agent description
account_id	String	Account unique identifier
status	Integer	See Agent status
timezone	String	Agent timezone
created_at	Date	Agent creation date
updated_at	Date	Agent update date
variables	Object Array	See Agent Variables

Agent Variable for Campaigns

This is a representation of an agent's variable in a campaign

Field	Type	Description
id	String	Variable identifier
name	String	Variable name
description	String	Variable description
type	Integer	See Variable data type
kind	Integer	See Lili variable type
created_at	Date	Variable creation date
updated_at	Date	Variable update date

Campaign

A Campaign is a feature within the platform that enables the configuration of how Lili will reach out to users. It allows defining contact details, such as which users to call, call schedules, the number of call attempts, the time between retries, and the campaign's start time, among other options. This tool is essential for both the technical team responsible for the setup and the end users who will receive Lili's communications.

Field	Type	Description	Format
id	String	Campaign unique identifier	UUID V4
name	String	The campaign name.	Text between 5 and 23 characters long
interval	String	Time interval between retries.	HH:MM:SS
number_calls	String array	The phone number to outbound calls	International phone number format
retries	Integer	Number of retries to make calls to a contact	0
contact_group	String	Is a uuid v4 for the campaign. This id is required for some operations as example, add contacts in a dynamically campaign.	UUID V4
timezone	String	The timezone to used in the campaign for calculate the available time and the start and finish date	TZ Name.
scheduled_type	Object	Set the window to make calls.	See Scheduled Type
start_date	String	The date time to start the campaign. When is empty the campaign starts now.	YYYY-MM-DD HH:MM
end_date	String	The date time to end the campaign. When is empty the campaign finish when all contacts and all retries will be done.	YYYY-MM-DD HH:MM
map	JSON	Used for set the match between the agent variables (the id) and the contact keys. If the agent no required any value from the contact data can be skip this field.	Key – value JSON
status	String	Campaign current status	See Campaign Status
dynamic_contact_group	Boolean	Configure the campaign for await new contacts while is active. When is false, only the contacts added before the campaign change to active will be called.	0
phone_fields	String array	The keys in the contact data that contain the phone number to call. If your contact group have this field mapped as “phone”, "Phone” you can skip this field, another case, you need set the the key or keys names in the array.	0
interval_phone_fields	String	The time to await between a contacts phone. The default value is "5m"
exclusion_groups	String array	List of Exclusion Groups used in this campaign
campaign_type	Integer	Campaign type	See Campaign Types
automatic_flow_id	String	Unique identifier for an Automated Flow previously defined at Admin Dashboard	UUID V4
automatic_flow_workflow_id	String	This represents an Automatic Flow instance for this campaign	UUID V4
current_automaticflow_node_id	String		UUID V4
parent_campaign_id	String		UUID V4

Contact confirmation

A Contact confirmation contains the result for current contact addition request, with a summary of successful

Field	Type	Description	Format
type	String	The scheduled windows type	See Scheduled Types
available_time_from	String	The hour of the day when the calls can start to send calls.	HH:MM:SS
available_time_to	String	The max our of the day when the call can be send.	HH:MM:SS

Contact Group Summary

This contains all contact information

Field	Type	Description	Format
contacts	Object	Represents an Uploaded contact. This structure can change according to data structure used to upload contacts	See Uploaded Contact
pagination	Object	The pagination object to move through pages and get all contacts by iteration	See Pagination object

Conversation record

Represents a conversation executed by an agent, and its result in terms of data captured during Lili and contact's interaction.

Name	Type	Description	Format
agent_id	String	Agent unique identiifer	UUID v4
attempt_id	Integer	Attempt number for conversation
billing	Float64	AI Seconds or minutes to be charged
call_answered	Boolean	Determines if a conversation was answered
call_contacted	Boolean	Determines if there was contactability during the conversation
call_direction	String	Determines conversation direction. INBOUND or OUTBOUND.
call_fallback	Boolean	Determines if a conversation ended in fallback
call_id	String	Initial unique identifier for conversation, for tracing purposes
call_transfered	Boolean	Determines if a conversation was transferred to human agents
campaign_id	String	Campaign unique identifier	UUID v4
campaign_name	String	Campaign name
channel_type	String	Channel type used in conversation
contact_confirmed	Boolean	Determines if contact was confirmed in a conversation
contact_phone	String	Contacts phone
contactability_type	String	Specifies contactability type got in a conversation
date	Date	Conversation timestamp
duration	Float64	Conversation duration. Used to determine billing units.
engagement	Boolean	Determines if a conversation reached engagement indicator
fallback_type	String	Specifies fallback type got in a conversation
hang_up_cause	String	Conversation final status
recall	Boolean	Determines if a conversation didn't meet minumum contactability requirements and needs to be executed again.
recall_type	String	Specifies recall type
retention	Boolean	Determines if a conversation reached retention indicator
sent_sms_nodes	Integer	Counter for SMS notifications sent during a conversation
sent_whatsapp_nodes	Integer	Counter for WhatsApp notifications sent during a conversation
session_id	String	Unique conversation identifier
succes	Boolean	Determines if a conversation got success
success_type	String	Specifies success type, defined by business case
transfered	Boolean	Determines if a conversation got transferred
variables	Object array	See Agent Variables

Performance analytics overview

Name	Type	Description
average_call_duration_sec	Float64	Average conversation duration, in seconds
average_interactions	Float64	Average interactions between contacts and Lili virtual agent
confirmed_by_contacted	Float64	Percentage of people who confirmed their identity over the number of contacts who were contacted
percentage_contactability	Float64	Percentage of people who interacted with the virtual agent out of the total number of contacts that had to be contacted
percentage_engagement	Float64	Percentage of conversations in which the contact interacted the minimum amount of times set up
percentage_retention	Float64	Percentage of people that ended a conversation properly over the total of people contacted
percentage_success_rate	Float64	Percentage of people who progressed to the point in the conversation where the goal is reached over the number of contacts who confirmed their identity
total_answered	Integer	Number of people who answered
total_call_ended	Integer	Number of sessions ended
total_confirmed	Integer	Number of sessions in which the person to contact confirms their identity
total_contactability	Integer	Number of people who interacted with the virtual agent
total_contacted	Integer	Number of sessions in which someone interacts at least once with the virtual agent
total_contacts	Integer	Number of people to be contacted
total_engaged	Integer	Number of conversations in which the contact interacted the minimum amount of times set up
total_recall	Integer	Number of conversations that recognized to be recalled
total_retention	Integer	Number of people that ended a conversation properly
total_success	Integer	Number of sessions in which the contact who confirmed their identity progressed to the point in the conversation where the goal is reached
total_voicemail	Integer	Number of conversations attended by a voicemail
call_record	Object array	See Conversation record

Uploaded Contact

Represents an specific contact.

Name	Type	Description	Format
id	String	Contact unique ID	UUID V4
account_id	String	Vozy account identifier	UUID V4
contact_group_id	String	Contact group identifier	UUID V4
created_at	String	Contact creation date	Creation date in HTTP format
updated_at	String	Contact update date	Update date in HTTP format
vozy_batch_id	String	Vozy internal identifier to determine on which request the contact was loaded	UUID V4
vozy_error_validation	String	When a contact fails internal validations, root cause is shared here
vozy_valid_field	Boolean	Validation result, true or false

Scheduled Type

A Scheduled Type represents the available working hours for Lili executing the current campaign

Field	Type	Description	Format
type	String	The scheduled windows type	See Scheduled Types
available_time_from	String	The hour of the day when the calls can start to send calls.	HH:MM:SS
available_time_to	String	The max our of the day when the call can be send.	HH:MM:SS

Enumerations

A number of resource fields will only accept a list of known values, as outlined in this section.

Agent Status

Agent status description

Status	Description
1	Pending: Agent is not ready to attend conversation. Needs configurations or training.
2	Failed: Something was wrong during NLP traing
3	Success: Agent is ready to use.
4	Init: Agent was just initialized.

Campaign Status

Campaign status description

Status Class	Description	Short format
CAMPAIGN_STATUS_ACTIVE	The campaign is running
CAMPAIGN_STATUS_PAUSED	the campaign is paused and no calling the contacts.	paused
CAMPAIGN_STATUS_SCHEDULED	The campaign was created with a start date set. Is pending for start.
CAMPAIGN_STATUS_RESUME	A campaign previously paused is running again.	resume
CAMPAIGN_STATUS_FINISHED	The campaign as end.	finish
CAMPAIGN_STATUS_CANCELED	The campaign was cancelled by user.	canceled
CAMPAIGN_STATUS_FAILED	Something is wrong in the agent or account configuration. Try again, if the status is the same, please contact to support.

Scheduled Types

Scheduled type	Description
anytime	Lili can start a conversation at any hour of the day.
businessHours	Lili can start a conversation between 8am and 8pm,.
custom	Set an specific interval on which Lili can start a conversation

Campaign Types

Campaign type	Description
1	General campaign
2	Automatic Flows campaign

Variable data Types

Variable data type	Description
1	String
2	Float64
3	Unix Time

Lili Variable Types

Lili variable type	Description
1	Constant
2	Entity
3	System

Errors

The Vozy API uses the following error codes:

Error Code	Meaning
400	Bad Request -- The api found a invalid field or format in the request sent. Check the error and fix the request with the valid format.
401	Unauthorized -- The key is missing in the request headers, is invalid or was disabled.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The resource requested has been removed from our servers
412	Precondition failed -- Campaign or other entity is in a status that blocks requested action
429	Too Many Requests -- You're hitting our rate limit! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.