logo
API docs by Redocly

Zenvia Customer Cloud - Sales API (1.0.0)

Download OpenAPI specification:Download

URL: https://www.zenvia.com/customer-cloud License: Apache 2.0

Overview

Welcome to our API reference!

This is the reference documentation for the REST API from Sales section of Zenvia Customer Cloud . This API is based on resources which are represented by JSON format and are manipulated using the HTTP protocol.

What can this API do?

  • Send Lead data for agents to work with.
  • Access the database of contacts.
  • Subscribe and be notified via webhooks when some events occur in Sales, i.e:
    • An interaction with a contact occurs. An interaction can be anything from a message to a reminder to an agent note.
    • A new contact is created.

And much more...

Prerequisites

Before using this API you will need:

  1. A Zenvia Customer Cloud account. You need to have an access to a Zenvia Customer Cloud account in order to use the API.
  2. An API Key. You can create a one-off API Key by installing the "API access" App from the App Marketplace.
  • Full-fledged Apps are granted one API Key per instance. See App Lifecycle for more information.

Glossary

These are some of the terms we use across the API.

Lead

In Sales, a lead is a piece of information that allows an agent to contact a potential client. To be useful, this information should include:

  • Contact information

Prospect

A contact or prospect can be added to Zenvia Customer Cloud in two ways:

  • From a lead, generally acquired through a marketing channel.
  • Manually by an agent using the Sales app.
  • It is important to understand that not every lead will generate a new prospect. Sales can detect duplicate leads and merge them into a single prospect.

Authentication

api_key

Requests made to the API must include a valid API Key as a query string parameter. For example:

GET 'https://sales.zenvia.com/api/v1/prospect/56b367bffdc27b03003fc3ee?api-key=YOUR_api_key'
Security Scheme Type: API Key
Query parameter name: api-key

API Scopes

API Keys enable access to the API with one or more Scopes. Each API Scope enables set of API features.

Scope Permissions
leads:write Send lead data for agents to work with.
prospects:read Read prospects, operations and quotes.
prospects:readAdditionalData Read prospects and quote additional data.
prospects:write Create new quotes, update quotes, delete prospects, etc.
notifications Subscribe to notifications via webhooks.
messages:channels List available conversational channels for prospects.
messages:transactional Send transactional messages like appointment information, delivery and shipping notifications.
messages:conversational Send conversational messages for automatic replies, chatbots, and other use cases.
integration:act-as-user Perform operations as a user.

Rate Limits

API Rate Limits are in place to protect Sales from API traffic spikes that could put our databases at risk. We therefore measure the amount of requests sent to the API in order to throttle these when they surpass the amount allowed. We will respond with 429 Too Many Requests and the following headers:

  • By default, we have set 200 RPM (Requests per minute) per API Key
Header Name Header Description
X-RateLimit-Limit Maximum number of requests allowed for the app.
X-RateLimit-Remaining Number of requests left in the current time.
X-RateLimit-Reset Time when the number of requests will be reset to the maximum limit.

When does the amount of requests reset?

The amount of permitted requests resets every 60 seconds

Leads

The following endpoints allow creating and registering Leads.

Send Lead

Processes lead data and returns the matching prospect. If the prospect already exists, previous lead data will not be returned.

Authorizations:
api_key
Request Body schema: application/json
required
priority
number

The priority of the Lead

provider
string

The name/key to identify the provider of the lead.

providerLeadId
string

The ID of the lead in the provider.

utmSource
required
string

Identify the advertiser, site, publication, etc. that is sending traffic to your property.

utmMedium
string

The advertising or marketing medium.

utmCampaign
string

The individual campaign name, slogan, promo code, etc. for a product.

firstName
string
lastName
string
phones
Array of strings
emails
Array of strings <email> [ items <email > ]
Array of objects (Nin)

National Identification Number

address
string

Full street address.

subLocality
string

County / other sub-division of a locality, such as communes departments, etc.

locality
string

City / Municipality.

region
string

State / Province.

country
string
zipCode
string

Zip Code / Postal Code.

listingTitle
string

The title of the listing page.

listingUrl
string

The URL of the listing page.

comments
string

Any comments worth making to the agent, from the lead or from the acquisition channel.

company
string

If the lead has an assigned company, indicate it's name or code. Usually, it's the name of the company under the general account.

store
string

If the lead has an assigned store, indicate it's name or code. Usually is the name of the branch inside the company.

agent
string

If the lead has an assigned agent, indicate it's email, phone or id.

leadId
string

@deprecated - use providerLeadId The ID of the lead in the provider.

source
string

@deprecated - use utmSource Identify the advertiser, site, publication, etc. that is sending traffic to your property.

medium
string

@deprecated - use utmMedium The contact medium where the lead came from.

campaign
string

@deprecated - use utmCampaign The individual campaign name, slogan, promo code, etc. for a product.

Array of objects (NewEvent)

Ordered list of lead events

object (Product)

Responses

Request samples

Content type
application/json
{
  • "priority": 0,
  • "provider": "Webmotors",
  • "providerLeadId": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "utmMedium": "referral, organic, cpc, email, social, video",
  • "utmCampaign": "Christmas / New Year campaign",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phones": [
    ],
  • "emails": [],
  • "nin": [
    ],
  • "address": "Jujuy 986, 1er piso, depto. \"A\"",
  • "subLocality": "La Perla",
  • "locality": "Mar del Plata",
  • "region": "Buenos Aires",
  • "country": "Argentina",
  • "zipCode": "7600",
  • "listingTitle": "MLA 641645231 Ferrari F430 F1 Spyder Cabriolet",
  • "listingUrl": "https://auto.mercadolibre.com.ar/MLA-641645231-ferrari-f430-f1-spyder-cabriolet-2006-roja-excelente-permuto-JM",
  • "comments": "I am interested in the Honda Civic. I will like to receive information about financing. I also have a Fiat Punto as trade in vehicle. Thanks!'",
  • "company": "Southern Group",
  • "store": "Freedom Branch",
  • "agent": "[email protected]",
  • "leadId": "string",
  • "source": "google, newsletter4, billboard, ford, bmw",
  • "medium": "cpc, banner, email newsletter, form.",
  • "campaign": "Christmas / New Year campaign",
  • "history": [
    ],
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "507f191e810c19729de860ea",
  • "group": "string",
  • "groupId": "507f191e810c19729de860ea",
  • "initialGroup": "string",
  • "initialGroupId": "507f191e810c19729de860ea",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

Prospects

Querying and Deleting Prospects (customers) and their interactions with agents.

getProspects

Returns a filterable list of prospects.

If a limit is not specified, the query will return prospects from the last 31 days

If a limit is not specified, but a date or range of dates are provided, the query will return prospects within the
date or dates specified. A range of dates is considered valid if the range between them is 31 days or less

Invalid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-10-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID

Valid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID

If only one of the dates is provided, the comparison will be made with the present date
Example:

  Assuming that the present date is 2020-10-28T03:00:00.000Z

  ?createdAfter=2020-08-01:T03:00:00.000Z -> INVALID
  ?createdAfter=2020-09-30:T03:00:00.000Z -> VALID
Authorizations:
api_key
query Parameters
before
string^[a-z0-9]{24}$

Limits the results only to the prospects created before the one provided in this parameter (not included)

after
string^[a-z0-9]{24}$

Limits the results only to the prospects created after the one provided in this parameter (not included)

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

search
string

A search string to filter prospects. It can be a phone number, an email address or a name.

phoneNumber
string

A phone number string to filter prospects

category
string

The category to filter prospects.

status
string

The status to filter prospects.

agent
string^[a-z0-9]{24}$

The id of an agent to filter prospects

createdAfter
string <date-time>

The start date to filter prospects by their creation date

start
string <date-time>

@deprecated - use createdAfter The start date to filter prospects by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter prospects by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter prospects by their creation date (alias of createdBefore).

claimedAfter
string <date-time>

The start date to filter prospects by their claim date.

claimStart
string <date-time>

The start date to filter prospects by their claim date (alias of claimAfter).

claimedBefore
string <date-time>

The end date to filter prospects by their claim date.

claimEnd
string <date-time>

The end date to filter prospects by their claim date (alias of claimBefore).

transferredAfter
string <date-time>

The start date to filter prospects by their transfer date

transferStart
string <date-time>

The start date to filter prospects by their transfer date (alias of transferredAfter)

transferredBefore
string <date-time>

The end date to filter prospects by their transfer date

transferEnd
string <date-time>

The end date to filter prospects by their transfer date (alias of transferredBefore)

withAgent
boolean

A boolean specifying whether a prospect has an assigned Agent or not

group
string^[a-z0-9]{24}$

The id of a group to filter prospects

additionalData
Array of strings

List of filters for additionalData on format [FIELD][OPERATOR][VALUE].

  • FIELD: Can be any additional data field
  • OPERATOR: Can be =, >=, >, <=, < or ~ (contains)
  • VALUE: Any string

/prospects?api-key{api_key}&additionalData[]=finance=1 Filter all prospect that have additionalData.finance and is equal to 1.

/prospects?api-key{api_key}&additionalData[]=birthdate<01/01/2000&additionalData[]=birthdate>=01/01/1990 Filter all prospect that have additionalData.birthdate, is greater or equal than 01/01/1990 and lower than 01/01/2000.

/prospects?api-key{api_key}&additionalData[]=style~blue Filter all prospect that have additionalData.style and contains blue string.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
[
  • {
    }
]

getProspectByParam

Returns a prospect searching by their phone number and/or email. Please notice that even both of these params being optionals, it is necessary to inform at least one of them for the request to be successful processed

Authorizations:
api_key
query Parameters
email
string

Email address string to search for

phoneNumber
string

A phone number string to search for

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "firstName": "John",
  • "emails": [],
  • "phones": [
    ],
  • "account": "507f191e810c19729de860ea",
  • "claimedBy": "507f191e810c19729de860ea"
}

getProspectById

Returns an specific prospect by its ID.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "507f191e810c19729de860ea",
  • "group": "string",
  • "groupId": "507f191e810c19729de860ea",
  • "initialGroup": "string",
  • "initialGroupId": "507f191e810c19729de860ea",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

getInteractions

Returns a filterable list of interactions.

If a limit is not specified, the query will return interactions from the last 31 days

If a limit is not specified, but a date or range of dates are provided, the query will return interactions within the
date or dates specified. A range of dates is considered valid if the range between them is 31 days or less

Invalid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-10-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID

Valid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID

If only one of the dates is provided, the comparison will be made with the present date
Example:

  Assuming that the present date is 2020-10-28T03:00:00.000Z

  ?createdAfter=2020-08-01:T03:00:00.000Z -> INVALID
  ?createdAfter=2020-09-30:T03:00:00.000Z -> VALID
Authorizations:
api_key
query Parameters
before
string^[a-z0-9]{24}$

Limits the results only to the prospects created before the one provided in this parameter (not included)

after
string^[a-z0-9]{24}$

Limits the results only to the prospects created after the one provided in this parameter (not included)

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

agent
string

The id of the agent to filter.

status
string

The status to filter.

createdAfter
string <date-time>

The start date to filter interactions by their creation date.

start
string <date-time>

@deprecated - use createdAfter The start date to filter interactions by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter interactions by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter interactions by their creation date (alias of createdBefore).

via
Array of strings
Items Enum: "walkIn" "sms" "whatsApp" "email" "testDrive" "visit" "phoneCall" "outboundCall" "inboundCall" "facebook"
format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
[
  • {
    }
]

getProspectInteractions

Returns a filterable list of interactions related to a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

query Parameters
status
string

The status to filter interactions.

createdAfter
string <date-time>

The start date to filter interactions by their creation date.

start
string <date-time>

@deprecated - use createdAfter The start date to filter interactions by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter interactions by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter interactions by their creation date (alias of createdBefore).

via
Array of strings
Items Enum: "walkIn" "sms" "whatsApp" "email" "testDrive" "visit" "phoneCall" "outboundCall" "inboundCall" "facebook"
format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
[
  • {
    }
]

transferProspect

Transfer a Prospect to a group

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
required

Define the destination user or group.

group
string (ObjectId) ^[a-z0-9]{24}$

Unique identifier of an object.

user
string (ObjectId) ^[a-z0-9]{24}$

Unique identifier of an object.

Responses

Request samples

Content type
application/json
{
  • "group": "507f191e810c19729de860ea",
  • "user": "507f191e810c19729de860ea"
}

Response samples

Content type
application/json
{
  • "success": true
}

Transactional Messaging

Sending transactional messages to prospects (beta)

getChannels

This endpoint returns the channels (communication channels) available in the scope of the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getChannelsByProspectId

Given an ProspectID, this endpoint returns the channels (communication channels) available for that prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

sendTemplateMessage

Send a transactional template message to a prospect

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: application/json
required
key
required
string

Template key

object

Optional parameters for overriding template parameters. The empty variables must not contain four consecutive spaces, carriage return, new line or tabulations. More information here: https://developers.facebook.com/docs/whatsapp/message-templates/creation

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "parameters": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Conversational Messaging

Sending conversational messages to prospects (beta)

getChannels

This endpoint returns the channels (communication channels) available in the scope of the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getChannelsByProspectId

Given an ProspectID, this endpoint returns the channels (communication channels) available for that prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

sendFile

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: multipart/form-data
required
required
object

The file to send to the prospect

Responses

Request samples 

var request = require('request');
var fs = require('fs');
var options = {
  'method': 'GET',
  'url': 'https://sales.zenvia.com/api/v1/prospect/${prospectId}/messaging/${channel}/send-file?api-key=${apiKey}',
  'headers': {
  },
  formData: {
    'file': {
      'value': fs.createReadStream('/Users/image.jpg'),
      'options': {
        'filename': 'image.jpg',
        'contentType': 'image/jpeg',
        'knownLength': 1024
      }
    }
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

sendMessage

Send a conversational message to a prospect

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: application/json
required
content
string

Message content

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Act as user

Doing actions as a Sales agent

getTransferable

Returns a list of groups and users the App can transfer prospects to.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "groups": [
    ]
}

getArchivingReasons

Returns the archiving reasons available to the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

transferProspectAsUser

Transfer a Prospect to a group or user. The integration (linked to the apiKey) must have a user configured. Also, the integrationType scope must have integration:act-as-user.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
required

Define the destination user or group.

group
string (ObjectId) ^[a-z0-9]{24}$

Unique identifier of an object.

user
string (ObjectId) ^[a-z0-9]{24}$

Unique identifier of an object.

Responses

Request samples

Content type
application/json
{
  • "group": "507f191e810c19729de860ea",
  • "user": "507f191e810c19729de860ea"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": "string"
}

archiveProspectAsUser

Archives a Prospect with an archiving reason. The integration (linked to the apiKey) must have a user configured. Also, the integrationType scope must have integration:act-as-user.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
required

The archiving reason that can be used

archivingReason
string

When the prospect is archived this property contains the code of the reason why it was filed.

firstName
string
lastName
string
phone
string

Phone to add to the prospect

email
string <email>

Email to add to the prospect

label
string

Change Label of the prospect

Responses

Request samples

Content type
application/json
{
  • "archivingReason": "string",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phone": "string",
  • "email": "[email protected]",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "507f191e810c19729de860ea",
  • "group": "string",
  • "groupId": "507f191e810c19729de860ea",
  • "initialGroup": "string",
  • "initialGroupId": "507f191e810c19729de860ea",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

Integrations

Getting information from integrations

checkCredentials

Check if API Key exists and if it is enabled.

query Parameters
api-key
required
string

API Key to check.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getIntegration

Returns the active integration

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "name": "string",
  • "providerKey": "string",
  • "groupId": "507f191e810c19729de860ea",
  • "group": "string",
  • "user": "507f191e810c19729de860ea",
  • "language": "string",
  • "account": "string",
  • "accountId": "507f191e810c19729de860ea"
}

getIntegrations

Returns the active integrations in the scope of the API Key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Agents

Getting information from agents

getAgents

Returns the agents from group

Authorizations:
api_key
query Parameters
group
required
string

The groups to get the agents.

active
string

Status of the agent/s.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
[
  • {
    }
]

isAgentWorking

Returns true or false depending on whether the agent is working.

Authorizations:
api_key
path Parameters
agentId
required
string^[a-z0-9]{24}$

The ID of the agent.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getAgentResponseTime

Returns media response time of the agent.

Authorizations:
api_key
path Parameters
agentId
required
string^[a-z0-9]{24}$

The ID of the agent.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

Groups

Getting information from groups

getGroups

Returns the groups that are within the scope of the App

Authorizations:
api_key
query Parameters
parent
string^[a-z0-9]{24}$

The ID of the parent group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getGroupsByLevel

Returns all immediate children of provided group. If no group is provided then the group where the API Access api-key is located will be assumed as the parent.

Authorizations:
None
query Parameters
parent
string^[a-z0-9]{24}$

The ID of the parent group.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getGroupById

Returns the group that corresponds to the given groupId

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "name": "string",
  • "parent": "string",
  • "ancestors": [
    ],
  • "descendants": [
    ],
  • "type": [
    ],
  • "timezone": "string"
}

isGroupWorking

Returns true or false depending if the group has at least one agent working.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getOnlineAgents

Returns all online agents for the provided group.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

query Parameters
availableAgents
boolean

Filter by available agents.

Responses

Response samples

Content type
application/json
{
  • "officeHours": true,
  • "agents": [
    ]
}

getGroupResponseTime

Returns media response time of the group.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

Webhooks

Webhooks allow you to receive notifications to a desired callback URL when something happens in Sales without constantly having to poll the API. Through the API, you can subscribe to the following topics: prospects (contacts), interactions (operations), quotes and agents.

You can review or delete the available subscriptions at any time, directly via the Notifications API.

Retries

If your service has problems handling notifications at any time, we will or will not attempt to re-send failed notifications depending on the case:

  • We will retry up to 20 times in the following cases:

    • Connection failed - If we cannot open an http connection to the provided webhook URL
    • Error codes - If your service responds with any HTTP status code (5xx)
    • Timeout - If your service takes longer than 10 seconds to send back a response

  • We will not retry in the following cases:

    • Response with statusCode < 500 (2xx, 3xx, 4xx)

    Successful and Failed Requests

Successful Request Failed Request
Status Code < 400 Timeout or Status Code >= 400

Prospects

Get notified of changes on prospects or when a new prospect is created.

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
whatsAppDueAt
string <date-time> (in case the prospect has an open Whatsapp conversation, this field indicates until when the window to send free messages is open)
facebookDueAt
string <date-time> (in case the prospect has an open Facebook Messenger conversation, this field indicates until when the window to send free messages is open)
updates
Array of objects (List of updates related to this prospect)
{
  • "subscriptionId": "string",
  • "topic": "prospects",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string",
  • "whatsAppDueAt": "2019-08-24T14:15:22Z",
  • "facebookDueAt": "2019-08-24T14:15:22Z",
  • "updates": [
    ]
}
Notification Payload change
New prospect created Type: “created”
The information of a prospect has been edited Type: “updated” "status": "followUp" / “archived”/”unclaimed”/”new”/etc “Updates”: list of changes

Interactions

Events related to existing or new interactions are notified in this topic.

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string (interactions)
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
object (Interaction)

Interactions are any kind of contact that an agent has with a prospect. This can be a phone call, a WhatsApp message, an email, a visit, etc.

{
  • "subscriptionId": "string",
  • "topic": "interactions",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string",
  • "interaction": {
    }
}

Interactions can have Type: “created” or Type: “updated”.

List of possible interactions:

  • New message sent to a client
  • New message received from a client
  • A Conversation Toolbar Button is clicked.
  • A client is transferred to another agent
  • New call to a client
  • A note is created on a chat with a client

Agents

Events related to agents (requires act-as-user scope).

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
{
  • "subscriptionId": "string",
  • "topic": "agents",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string"
}
Notification Payload change
Prospect created from the agent that is acting on behalf of. "type": "created"
Prospect transfer to the agent that is acting on behalf of. "type": "updated" "updates":

getTopics

Returns information about the available notification topics. Topics can be subscribed to using Subscriptions.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getActiveSubscriptions

Returns the list of active subscriptions. Note that subscriptions are currently limited to one per group.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

newSubscription

Subscribe to notification topics. Note that subscriptions are currently limited to one per group, and subscribing twice will result in the first subscription being deactivated.

Authorizations:
api_key
Request Body schema: application/json
required
topics
required
Array of strings

An array of topic names to subscribe to. Use the Notification Topics endpoint to see the available topics.

callbackUrl
required
string

Responses

Request samples

Content type
application/json
{
  • "topics": [
    ],
  • "callbackUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

getActiveSubscriptionById

Returns an active notification subscription by its ID.

Authorizations:
api_key
path Parameters
subscriptionId
required
string^[a-z0-9]{24}$

The ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

deactivateSubscription

Deactivates a subscription by its ID.

Authorizations:
api_key
path Parameters
subscriptionId
required
string^[a-z0-9]{24}$

The ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

App Lifecycle

Apps should handle the following lifecycle webhooks from Sales. All requests that originate from Sales will include the corresponding Client ID and Secret, and Apps should reject requests with missing or invalid credentials. All requests from Sales include the API Key of the App instance as context.

POST create

Sales will call this endpoint whenever a new App instance is installed. This request will include essential information for the App instance like its API Key and initial state.

The App should store the API Key as it will be needed for future calls to the Sales API. See Authentication.

appId
string
appSecret
string
object
{
  • "appId": "APP_ID",
  • "appSecret": "APP_SECRET'",
  • "integration": {
    }
}

GET form

Apps can design a settings form layout by returning a JSON object with the following schema:

title
string

A title for the form.

description
string

A description for the form. CommonMark syntax MAY be used for rich text representation.

hint
string

A relevant note that the third-party want to communicate to the user. CommonMark syntax MAY be used for rich text representation.

warning
string

An warning that the third-party want to communicate to the user, but that does not prevent submit the form data. CommonMark syntax MAY be used for rich text representation.

error
string

An error that prevents sending the form. CommonMark syntax MAY be used for rich text representation.

required
Array of objects

A list of sections for the form

Array of objects

A list of validation that allow to the third-party to modify the form based on data completed by the user

{
  • "title": "string",
  • "description": "string",
  • "hint": "string",
  • "warning": "string",
  • "error": "string",
  • "sections": [
    ],
  • "validations": [
    ]
}

When the user saves changes to the App settings, Sales will use the names of the inputs as keys and send them to the PUT settings App Lifecycle endpoint.

GET settings

Sales will request the App for a settings object from time to time. Apps can store any relevant settings needed for the App instance.

The keys in the settings object should match with the form inputs names, so they can be edited in the App settings screen by the user.

App response example

{
  "automaticReplyEnabled": true
}

PUT settings

Whenever a user changes the App settings, Sales will send the updated settings object to this endpoint. It is recommended to make a merge with the updated settings since Sales will just send the new ones and not the entire set.

Request payload example

{
  "automaticReplyEnabled": false
}

PUT enabled

Whenever a user disables or enables the App, Sales will notify the App backend of this. Use this to pause or resume the execution of your App instance if applicable.

Any call made to the API by a disabled App will return an error.

enabled
boolean
{
  • "enabled": true
}

PUT api-key

Sales may refresh the App's API Keys at any time, and send the new API Key using this endpoint. Avoid using API Keys that have been refreshed.

newApiKey
string
{
  • "newApiKey": "abc123"
}

DELETE app

Whenever a user deletes the App, Sales will notify the App backend of this and will 'soft' delete it (logical delete)

Response example

{
  "success": true
}

Flow of requests Sales does when creating an App:

  1. GET settings: Without an apiKey. The default settings should be returned in the response. These are used to create an App instance.
  2. GET form: Without an apiKey. The form's structure should be returned in the response.
  3. POST create: With apiKey on the body, Sales will send everything needed to save the App and will expect in return an OK status.
  • From here, any request will have the apiKey.

Extension Points

App developers can leverage the following Extension Points, allowing them to go beyond what is possible to achieve as a Sales user or through the API.

Reports

Apps may add custom reports to the Reports section for managers to use. Users can interact with the App directly through these embedded reports.

Report definition schema:

key
string

Unique identifier for the report.

name
string

Report name and title. Must be localizable.

url
string <uri>

Report URL. May contain placeholders.

{}

Query parameters

Sales will add the following query parameters automatically:

Query Parameter Description Example
range Date range of the Report. Can be last-month, this-month, yesterday, today, last30, last7 or custom custom
start Report starting date in YYYY-MM-DD format (only applies for range=custom) 2020-12-01
end Report ending date in YYYY-MM-DD format (only applies for range=custom) 2020-12-31
group ID of the group selected for the report 507f191e810c19729de860ee
parentGroup ID of the group of the user viewing the report 507f191e810c19729de860ef
signature See Request signature below a08116905e92633e4f30eefd1276206b259305c8783642fc5b7f51c089187939

Report URL Placeholders

The report URL may contain placeholders as follows:

https://app.example.com/prospect/${prospect._id}?lang=${group.language}

Supported placeholders:

Placeholder Description Example
user._id ID of the user viewing the report 507f191e810c19729de860ea
user.firstName First name of the user Jorge
user.lastName Last name of the user Letona
user.cellPhone Cell Phone number of the user +15417543010
user.phone Phone number of the user +15417543010
user.email Email of the user [email protected]
group._id ID of the group of the user viewing the report 507f191e810c19729de860ec
group.name Name of the group Sales
group.language Language of the group in ISO 639-1 format en
group.displayName Display name of the group Sales

Conversation Toolbar Buttons

Apps may add custom buttons to the conversation toolbar for agents to use. Once clicked, these buttons open embedded dialogs where the agent can interact with the App directly.

Button definition schema:

key
string

Unique identifier for the button.

name
string

Button name and label. Localizable.

url
string <uri>

Embedded dialog URL. May contain placeholders.

icon
string <data-uri>

Icon in Data URI format. A 64x64 px PNG image is recommended.

{}

Query parameters

Sales will add the following query parameters automatically:

Query Parameter Description Example
signature See Request signature below a08116905e92633e4f30eefd1276206b259305c8783642fc5b7f51c089187939

Dialog URL Placeholders

The URL can contain placeholders as follows:

https://app.example.com/prospect/${prospect._id}?lang=${group.language}

Supported placeholders:

Placeholder Description Example
prospect._id ID of the contact whose conversation the button is clicked on 507f191e810c19729de860ea
prospect.firstName First name of the contact John
prospect.lastName Last name of the contact Smith
prospect.phones Phone numbers of the contact. Numbers must be comma separated. +15417543010
prospect.emails Emails of the contact. Numbers must be comma separated. +15417543010
user._id ID of the user viewing the report 507f191e810c19729de860ea
user.firstName First name of the user Jorge
user.lastName Last name of the user Letona
user.cellPhone Cell Phone number of the user 15417543010
user.phone Phone number of the user 15417543010
user.email Email of the user [email protected]
group._id ID of the group 507f191e810c19729de860ea
group.name Name of the group Sales
group.language Language of the group in ISO 639-1 format en
group.displayName Display name of the group Sales
prospect.source Source of the contact Whatsapp
prospect.providerLeadId External id of the contact ABC-123-xyz

Request signature

In order to avoid the forging of requests, Sales adds a signature parameter. To verify it follow these steps:

  1. Get the signature query parameter. Make a copy of the request URL WITHOUT the signature.
  2. Create an HMAC using the URL without signature and the App's Private Key. Node.js example:
    const hmac = crypto.createHmac('sha256', PRIVATE_KEY)
hmac.update(URL)
const EXPECTED_SIGNATURE = hmac.digest('hex')
  3. Compare the signature with EXPECTED_SIGNATURE and reject the request if they don't match.

Prospect Fields

An array of fields to add to the prospect and user entities, respectively. Each field definition contains the following elements:

  • key: Unique identifier for the field.
  • type: Type of field. Can be text, dropdown or date.
  • name: Field name and label. Localizable.
  • hint: Field hint. Localizable.
  • options: Only valid for type: 'dropdown'. An array of options. Each option has the following elements:
    • text: Option display. Localizable.
    • value: Option string value.
  • required: Boolean indicating if the field is required or optional.
  • validationRegex: A regular expression to validate the field values against. Only valid for type: 'text'. Optional.
  • validationError: Error message when validation fails. Use in conjunction with validationRegex. Localizable. Optional.

User Fields

An array of fields to add to the prospect and user entities, respectively. Each field definition contains the following elements:

  • key: Unique identifier for the field.
  • type: Type of field. Can be text, dropdown or date.
  • name: Field name and label. Localizable.
  • hint: Field hint. Localizable.
  • options: Only valid for type: 'dropdown'. An array of options. Each option has the following elements:
    • text: Option display. Localizable.
    • value: Option string value.
  • required: Boolean indicating if the field is required or optional.
  • validationRegex: A regular expression to validate the field values against. Only valid for type: 'text'. Optional.
  • validationError: Error message when validation fails. Use in conjunction with validationRegex. Localizable. Optional.

Localization

All localizable strings need an English variant that will be used by default and may define additional variants for other languages or locales.

They should be objects with the following schema:

fieldName: {
  en: 'Text in English', // mandatory
  es: 'Text in Spanish',
  pt: 'Text in Portuguese'
}