The Conversica Platform is a cloud-based SaaS platform that powers a proprietary conversational artificial intelligence (AI) system that provides Customers with the ability to follow up on Leads by engaging them in real-language conversation. The Conversica Platform supports a number of AI-powered assistants for different business functions. For example, once the Revenue Digital Assistant for Sales establishes a determined level of interest from the Lead, the Lead is escalated and handed off to the Customer’s sales team for follow-up.
The Conversica API allows Customers to:
- Transport Lead data between the Customer System and the Conversica Platform
- Receive Lead Update data from the Conversica Platform
- Receive Message data for associated Leads from the Conversica Platform
Before utilizing your Application, you agree to cooperate with us by testing the Application as we designate for quality assurance and approval, and you agree to not use nor enable an Application prior to our approval.
Terms & Definitions
- Lead: The data containing relevant information for communication by the Conversica Assistant with a Customer’s prospects. Depending on the Conversation and Assistant in use, a Lead may be a lead, contact, customer, account, prospect, or other related entity.
- Message: The communication between the Conversica Assistant and the Lead. This includes communication both sent to and received from the Lead.
- Conversation: The conversational skill employed by the Conversica Assistant when messaging a Lead, and with a specific objective to meet. For example, “Engage Demand” for real-time or inbound Leads.
- Conversation ID: For a particular Conversation, a list or filtered set of Leads (e.g. “campaign” in someCRMs) for the purpose of tailoring messaging to a more specific audience or use case.
- Assistant: The Conversica artificial intelligence persona that engages in two-way conversations with a Customer’s Leads.
- Salesperson: The “Lead owner” or representative that will be contacting or otherwise interacting with the Lead on behalf of the Customer once prompted by their Conversica Assistant.
- Customer: The authorized party responsible for posting Leads to Conversica and then receiving data back from Conversica to be utilized or displayed within their System.
- Customer System: The system used by the Customer to manage Leads and their associated data (e.g. a CRM or marketing automation system).
Data Flow
Summary
The Conversica API facilitates the flow of Lead data from the Customer System to the Conversica Platform, as well as the flow of Lead Update and Message object data from the Conversica Platform back to the Customer System. This is all performed using JSON-encoded POST requests.
Diagram
Key Types & Values
- All keys with a “datetime” type must contain UTC values following the RFC 3339 standard; e.g. 2019-05-10 T 05 : 57 : 44 + 00 : 00
- All keys with a “boolean” type must contain values true or false
Authentication
Method
The Conversica API uses HTTPS basic access authentication for the secure transmission of data between the Customer System and the Conversica Platform endpoints.
Conversica & Customer Endpoints
Endpoints provided both by the Customer and Conversica must use HTTPS basic access authentication:
- Conversica will provide a username and password for the Customer to use when connecting to the Conversica endpoints
- Customer will provide Conversica with a single username and password set for connecting to the Customer’s endpoints.
*There is a five character minimum for API usernames.
Conversica will provide one endpoint (see above) for receiving Lead object data. Customer will provide two endpoints, one for Message object data and one for Lead Update object data. To reiterate, both Customer endpoints should share the same username and password for HTTPS basic access authentication.
Conversica Endpoint
https://integrations-api.conversica.com/json/
Example Customer Endpoints
https:// api.customername.com /conversicaMessage/ https:// api.customername.com /conversicaLead/
API Username & Password
When ready for development, the Customer may contact their Conversica technical account manager to receive a username and password for authentication to the Conversica endpoint.
Connection Testing
Curl & PHP Example
The following connection test will return a status code and results:
<?php //Set payload and other params for Conversica API Request $data = [ 'apiVersion' => '7.2' , 'id' => '123456789' , 'conversationId' => '123' , 'firstName' => 'Sally' , 'email' => 'sally@email.com' , 'leadSource' => 'My Big Event 2019' , 'repName' => 'John' , ]; $url = 'https://integrations-api.conversica.com/json/' ; $header = [ 'Content-type: application/json' ]; $user = 'valid_username' ; $pass = 'valid_password' ; $data = json_encode($data); $ch = curl_init(); curl_setopt($ch, CURLOPT_USERPWD, $user . ":" . $pass); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HTTPHEADER, $header); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); //Execute request $result_string = curl_exec($ch); $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
Code | Title | Description |
---|---|---|
200 | OK | The request was successful |
400 | Bad Request | The request could not be understood due to an error |
401 | Unauthorized | The request could not be processed due to authentication |
Objects
Lead Object
Overview
The Lead object includes data relevant for communication between the Conversica Assistant and the Customer’s Leads. Some keys listed below are optional. However, Conversica recommends including as much information as possible for each Lead, in order to enhance the performance of your Assistant.
Keys & Values
Key | Type | Description | Required |
---|---|---|---|
apiVersion | String | The version number of the Conversica API in use | Yes |
id | String | The Lead’s unique ID in the Customer’s System (Source ID) | Yes |
conversationId | String | For a particular Conversation, a list or filtered set of Leads (e.g. “campaign” in some CRMs) for the purpose of tailoring messaging to a more specific audience or use case | No |
firstName | String | The Lead’s first name, used in messaging | Yes |
String | The Lead’s primary email address for messaging | Yes | |
leadSource | String | The source of the Lead, as indicated in the Customer’s System and as used by Conversica for either reporting on Lead Source performance or other customizations | Yes |
leadStatus | String | The status of the Lead, as indicated in the Customer’s System and as used by Conversica for intelligent Conversation management (e.g. “New,” “Sold,” or “Lost”) | No |
optOut | Boolean | Indicates whether or not the Lead has opted out of all methods of marketing and contact (“global” opt-out) | No |
repId | String | The Salesperson’s (Lead owner) unique ID in the Customer’s System | No |
repName | String | The Salesperson’s (Lead owner) name, used in messaging | Yes |
clientId | String | Unique ID for the Customer in the Customer’s System (Required if the API integration will be used for multiple Conversica Customers) | No |
lastName | String | The Lead’s last name | No |
homePhone | String | The Lead’s primary phone number | No |
workPhone | String | The Lead’s work phone number | No |
cellPhone | String | The Lead’s cell phone number (Required for SMS) | No |
address | String | The Lead’s street address | No |
city | String | The Lead’s city | No |
state | String | The Lead’s state | No |
zip | String | The Lead’s zip code | No |
leadType | String | The type of the Lead, as indicated in the Customer’s System (e.g. “Internet,” “Web Form,” or “Phone-In”) | No |
date | Datetime | The date and time the Lead was created in the Customer’s System (UTC RFC 3339 format) | No |
smsOptOut | Boolean | Indicates whether or not the Lead has opted out of being contacted by SMS text messaging (Required for SMS Conversations) | No |
stopMessaging | Boolean | If set to “true,” the Assistant will stop listening for responses and will no longer message the Lead | No |
skipToFollowup | Boolean | If set to “true,” the Assistant will wait a few days before sending a follow-up message | No |
repEmail | String | The Salesperson’s (Lead owner) email address | No |
smsOptIn | Boolean | If set to ‘true,’ indicates the Lead has accepted being contacted by SMS text messaging (Required for SMS Conversations) | No |
Code Example (JSON)
{ "apiVersion": "7.2" , "id": "12345" , "conversationId": "My Big Event 2019" , "firstName": "Sally" , "email": "sally@email.com" , "leadSource": "Big Events" , "leadStatus": "New" , "optOut": false , "repId": "98765" , "repName": "John" }
Message Object
Overview
The Message object includes data pertaining to the messages and responses between the Conversica Assistant and a Lead. All keys listed below are required.
Keys & Values
Key | Type | Description | Required |
---|---|---|---|
apiVersion | string | Version number of the Conversica API in use | Yes |
id | string | The Lead’s unique ID in the Customer’s System | Yes |
clientId | string | Unique ID for the Customer in the Customer’s System (Required if the API integration will be used for multiple Conversica Customers) | No |
action | string | Indicates whether the message was “sent” (by the Assistant) or “received” (from the Lead) | Yes |
date | datetime | The date and time the message was sent or received | Yes |
subject | string | The subject of the message sent or received | Yes |
body | string | The body of the message sent or received | Yes |
Code Examples (JSON)
{ "apiVersion": "7.2" , "id": "12345" , "clientId": "67890" , "action": "sent" , "date": "2019-05-10T05:57:44+00:00" , "subject": "Your online request" , "body": "Hi Sally, \nThanks for reaching out to us online. Would you like to schedule a demo with one of our representatives to learn more about our product? \nSincerely, \nJohn" }
{ "apiVersion": "7.2" , "id": "12345" , "clientId": "67890" , "action": "received" , "date": "2019-05-10T05:57:44+00:00" , "subject": "Re: Your online request" , "body": "Hi John \nSure, I have some time tomorrow after 3 pm Pacific, if that works? \nThanks, \nSally" }
Lead Update Object
Overview
The Lead Update object includes data containing updates about the Lead and Conversation. Other than “apiVersion,” “id,” and “clientId,” only keys with updated values will be sent per request. This data can be used by the Customer to represent the current status of a Lead or Conversation.
Keys & Values
Key | Type | Description | Required |
---|---|---|---|
apiVersion | String | Version number of the Conversica API in use | Yes |
id | String | The Lead’s unique ID in the Customer’s System | Yes |
clientId | String | Unique ID for the Customer in the Customer’s system (Required if the API integration will be used for multiple Conversica Customers) | No |
dateAdded | Datetime | The date and time the Lead was added to Conversica | No |
firstMessageDate | Datetime | The date and time the Conversica Assistant sent their first message to the Lead | No |
lastMessageDate | Datetime | The date and time the Conversica Assistant last sent a message to the Lead | No |
lastResponseDate | Datetime | The date and time the Conversica Assistant last received a response from the Lead | No |
hotLead | Boolean | If set to “true,” indicates the Lead has expressed interest and is ready to be contacted by the Salesperson | No |
hotLeadDate | Datetime | The date and time the Lead became a Hot Lead | No |
leadAtRisk | Boolean | If set to “true,” indicates the Lead was interested but has yet to be contacted by the Salesperson | Yes |
leadAtRiskDate | Datetime | The date and time the Lead became a Lead at Risk | No |
actionRequired | Boolean | If set to “true,” indicates the Lead’s response requires review by the Salesperson, and the Conversica Assistant has stopped messaging | No |
actionRequiredDate | Datetime | The date and time the Lead was set as Action Required | No |
discoveredPhone1 | String | A new and unique phone number detected by the Conversica Assistant while messaging the Lead | No |
discoveredPhone2 | String | A new and unique phone number detected by the Conversica Assistant while messaging the Lead | No |
discoveredEmail1 | String | A new and unique email detected by the Conversica Assistant while messaging the Lead | No |
discoveredEmail2 | String | A new and unique email detected by the Conversica Assistant while messaging the Lead | No |
leadStatus | String | Indicates an actionable Status for the Lead, either during or after engagement with the Conversica Assistant | No |
leadStatusDate | Datetime | The date and time the Lead entered into the current Conversica Lead Status | No |
conversationStage | String | Indicates the current Stage of the Conversation | No |
conversationStageDate | Datetime | The date and time the Conversation entered into the current Conversica Conversation Stage |
No |
conversationStatus | String | Indicates the current Status of the Conversation | No |
conversationStatusDate | Datetime | The date and time the Conversation entered into the current Conversica conversation Status | No |
doNotEmail | Boolean | If set to “true,” indicates the Lead has requested to no longer be contacted by email | No |
smsOptin | Boolean | If set to ‘true,’ indicates the Lead has accepted being contacted by SMS text messaging | No |
smsOptOut | Boolean |
If set to ‘true,’ indicates the Lead has requested to not be contacted by SMS/text messaging |
No |
Code Examples (JSON)
{ "apiVersion": "7.2" , "id": "12345" , "clientId": "67890" , "dateAdded": "2019-05-24T19:14:55+00:00" , "firstMessageDate": "2019-05-24T19:24:55+00:00" , "lastMessageDate": "2019-05-24T19:27:55+00:00" , "lastResponseDate": "2019-05-25T12:06:55+00:00" , "hotLead": true , "hotLeadDate": "2019-05-25T12:06:55+00:00" , "discoveredPhone1": "5558675309" , "doNotEmail": false,
"smsOptIn":true }
{ "apiVersion": "7.2" , "id": "12345" , "clientId": "67890" , "leadStatus": "None" , "leadStatusDate": "2019-05-24T19:24:30+00:00" , "conversationStage": "Messaging" , "conversationStageDate": "2019-05-24T19:24:30+00:00" , "conversationStatus": "Sent Message" , "conversationStatusDate": "2019-05-24T19:24:30+00:00" }
Appendix
Conversica Lead Status
Conversica Lead Status values indicate an actionable Status for the Lead, either during or after initial engagement with the Conversica Assistant. The values are best understood in the context of the “objective” of the Conversation, or the “goal” of the Assistant. For example, if the Status value is "Satisfied", this indicates the objective of the Conversation has been successfully met, as confirmed by the Lead’s response to follow up
Value | Description |
---|---|
Hot Lead | Indicates the Lead expressed interest and is ready for next steps (e.g. transition to the human Salesperson, scheduling an appointment/demo, etc.) |
Lead to Review | Indicates the Lead’s reply requires human review to determine the Salesperson’s next action. In this Status, the Conversica Assistant will no longer message the Lead |
Further Action | Indicates the Lead is still interested and has requested assistance with open questions or actions from their assigned Salesperson |
Satisfied (New) | Indicates the Lead responded positively to follow up (e.g. “Did you get what you requested?”), and the objective of the Conversation has been met |
Disqualified | Indicates the Lead responded to follow up such that they no longer require assistance (i.e. the objective of the Conversation has not been met, but they do not desire continued engagement) |
No Further Action | Indicates the Lead responded positively to follow up, such that they no longer require contact or assistance, though it is unclear if the objective of the Conversation has been met |
Conversica Conversation Stage & Status
Conversica Conversation Stage and Status values are keys/fields useful for understanding where the Lead is currently in the flow of messaging or engagement with the RDA.
Stage |
Status | Description |
Preparing Lead |
Preparing Lead |
Lead has been received by Conversica and has not been scheduled for first message. |
First Message Schedule | Lead has its first message scheduled, but not sent. | |
Messaging |
Sent Message |
Lead has been sent at least one message and no response to the current series has been received. |
Out of Office |
Received out of office message: Lead will remain in this status until the next message is sent (based on date extracted). | |
Checking Back Later |
Received message asking to check back later, lead will remain in this status until follow-up check back later message is sent. | |
Received Response |
System is reviewing response. | |
Message Scheduled |
Next message is scheduled but not yet sent; Typically due to worktimes; Status changes to "Sent Message" on sending. | |
Excluded |
Excluded (Lead Source) |
Client requested specific lead source not be worked. |
Excluded (Rep) |
Client requested specific rep's leads not be worked. | |
Excluded (Lead Status) |
Client requested specific lead status not be worked. | |
Excluded (Rule) |
Other reasons for exclusions, typically a client rule. | |
Unworkable |
No Rep Assignment |
System is missing rep and no primary rep is set. |
Duplicate (Internal) |
Lead is a duplicate of earlier lead from client. | |
Duplicate (CRM) |
Client CRM marked lead as duplicate. | |
Duplicate (External) |
Lead is a duplicate of earlier lead from another client. | |
Invalid Email |
Lead is invalidated by email verification system. | |
Malformed Email |
Lead does not have correct email address format. | |
No Email |
Lead does not have an email address. | |
Bounced |
Message could not be delivered to mailbox due to three soft bounces (e.g. mailbox is full) or one hard bounce (e.g. domain does not exist). | |
Lead Stopped |
Unsubscribed |
Lead clicked unsubscribe link in message. |
Marked Spam |
Lead marked message as Spam. | |
Do Not Email |
Lead was marked as Do Not Email by Conversica system. | |
Lead Requested Stop |
Conversica system interprets that lead wants messaging to stop for whatever reason. | |
No Longer at Company |
Conversica system interprets from response that the lead can no longer be contacted at the provided email address. | |
Client Stopped |
Manager Stopped |
Rep's manager stopped messaging. |
Rep Stopped |
Rep stopped messaging. | |
Admin Stopped |
Client Admin stopped messaging. | |
Inactive Service |
Lead deactivated due to an inactive (terminated) service. | |
CRM Stopped |
Client's CRM stopped messaging through the Conversica Options field. | |
Client Requested Stop |
Conversica Customer Success stopped messaging (on request from client). | |
Conversica Stopped |
Listening |
Leads that do not respond with seven days after the last message in series; lead could move to Messaging/Response Received if a response is received. |
Pause Limit Exceeded |
Paused leads that have passed the limit for being worked. | |
Marked Sold |
Lead marked as having already purchased. | |
Conversation Complete |
Conversation with lead is complete; system is not expecting any further responses. | |
System Stopped |
Response is such that the system cannot continue messaging, but the lead did not request stop; closely related to Review Response (formerly Action Required). | |
Service Not Active |
Service for lead is not active; lead has not been messaged. |
Automotive Industry-specific Keys & Values (Lead Object)
Overview
The Lead object includes data relevant for communication between the Conversica Assistant and the Customer’s Leads. The following keys are specifically for Automotive industry use, and are designed to function uniquely with those Assistants and related services. Some keys listed below are optional. However, Conversica recommends including as much information as possible for each Lead, in order to enhance the performance of your Assistant
Key | Type | Description | Required |
---|---|---|---|
leadSubStatus | String | The sub-status of the Lead, as indicated in the Customer’s System and as used by Conversica for intelligent Conversation management | No |
appointmentStatus | String | Indicates the current appointment status/stage for the Lead in the Customer’s System (e.g. “Scheduled”) | No |
appointmentDate | DateTime | The date and time the Lead entered into the current appointment status | No |
bdcRepId | String | The BDC representative’s unique ID in the Customer’s System | No |
bdcRepName | String | The BDC representative’s name, used in messaging | Yes |
bdcRepEmail | String | The BDC representative’s email address | Yes |
serviceRepId | String | The service advisor’s unique ID in the Customer’s System | No |
serviceRepName | String | The service advisor’s name, used in messaging | No |
serviceRepEmail | String | The service advisor’s email address | No |
year | String | The year of either the vehicle of interest or the primary vehicle associated with the Lead (e.g. “2019”) | Yes |
make | String | The make of either the vehicle of interest or the primary vehicle associated with the Lead (e.g. “Volkswagen”) | Yes |
model | String | The model of either the vehicle of interest or the primary vehicle associated with the Lead (e.g. “Atlas SEL”) | Yes |
vin | String | The vehicle identification number of either the vehicle of interest or the primary vehicle associated with the Lead (e.g. “1N4AL2APXBC154449”) | No |
Code Example (JSON)
{ "apiVersion": "7.2" , "id": "12345" , "clientId": "67890" , "firstName": "Sally" , "lastName": "Jones" , "email": "sally@email.com" , "homePhone": "3609483728" , "leadType": "Internet" , "leadStatus": "New" , "leadSource": "www.leadsource.com" , "date": "2017-01-10T15:19:21+00:00" , "repName": "John Doe" , "repId": "23254" , "repEmail": "john@dealershipname.com" , "bdcRepName": "Sheila Smith" , "bdcRepId": "20582" , "bdcRepEmail": "sheila@dealershipname.com" , "serviceRepName": "Billy Brown" , "serviceRepId": "20143" , "serviceRepEmail": "billy@dealershipname.com" , "year": "2019" , "make": "Volkswagen" , "model": "Atlas SEL" , "vin": "1N4AL2APXBC154449" , "appointmentStatus": "Scheduled" , "appointmentDate": "2017-01-10T15:19:21+00:00" , "optOut": false , "smsOptOut": true , "stopMessaging": false , "skipToFollowup": true }
Comments
0 comments
Article is closed for comments.