Conversation API (1.0)

Download OpenAPI specification:Download

DANAConnect: support@danaconnect.com URL: https://www.danaconnect.com License: Apache 2.0

The Conversation API is a REST web service that enables you to trigger smart conversation flows to a contact or a segment of contacts. A smart conversation flow is an automated workflow process implemented on the DANAConnect platform that is used to send messages to customers through different channels such as email, sms, push and others.

Considerations prior to using the API

  • The company that is going to use the API must have a valid username and password in the DANAConnect platform.
  • For security reasons, the user who is going to use the API must have a special permission. Your DANAConnect Account Manager must ensure that this permission is enabled.
  • This API works on Conversations (flows) that have previously been created and are active in the platform. This means that you must have the Conversation ID (conversationID) for this flow.
    What is the Conversation identification number (conversationID)?
    The conversation identification number in DANAConnect can be found on the activation reports page for each flow inside the Conversation Manager. It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
  • You must have the codes of the required fields in the database that is used with this conversation.
    Example:
    Conversation with ID (123456) would require the following fields codes:
    • NAME
    • SURNAME
    • EMAIL
    • DEBT
    • EXPIRATION_DATE

How to find the Conversation ID

For most DANAConnect API requests, you will need to send the Conversation ID as a parameter.
This conversation ID refers to the number assigned to the activation of the flow and can be found by logging into the DANAConnect platform and looking in the activation report for the conversation you need to refer to. It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
Here is a video explaining how to find the conversation ID:

Authentication

basicAuth

The API uses the same user credential system that is used to enter the DANAConnect platform.
The method used for all DANAConnect APIs is HTTP BASIC AUTH, which is based on login and password authentication.
Login: The login consists of the username concatenated with an @ and followed by the company code.
Login example:

  • Platform username: myuser
  • Company code for the platform: mycompanycode
  • Login for DANAConnect API: myuser@mycompanycode
  • Password: The password you should use for API authentication is the same as you use for login to the DANAConnect platform
Security Scheme Type HTTP
HTTP Authorization Scheme basic

ConversationAPI

ConversationAPI Endpoint

Start Conversation List

Starts a conversation with the preloaded list

Authorizations:
basicAuth
path Parameters
conversationID
required
integer <int32> >= 1

Indicates the id of the conversation to be executed

Example: 200897
header Parameters
X-DEBUG
integer <int32> [ 0 .. 1 ]
Default: 0

Header that activates debug mode of conversations

Example: 1

Responses

Request samples 

const fetch = require('node-fetch');  

async function makeRequest(){ 
    const conversationId = '<ConversationID>'; 
    const resp = await fetch( 
        `https://appserv.danaconnect.com/api/1.0/rest/conversation/${conversationId}/start/list`, 
        { 
            method: 'POST', 
            headers: { 
                'X-DEBUG': '0', 
                Authorization: 'Basic ' + Buffer.from('<username>@<companyCode>:%<Password>').toString('base64') 
            } 
        } 
    ); 
    const data = await resp.text(); 
    console.log(data); 
} 

makeRequest()

Response samples

Content type
application/json
Example
Successful Request
Successful Request
Unsuccessful Request

Result of a successful request

{
  • "wsResult": {
    }
}

Start Conversation with the data provided

Starts a conversation with one new record using the data given in the JSON

Authorizations:
basicAuth
path Parameters
conversationID
required
integer <int32> >= 1

Conversation Id to be started

Example: 200897
header Parameters
X-DEBUG
integer <int32> [ 0 .. 1 ]
Default: 0

Header that activates debug mode of conversations

Example: 1
Request Body schema: application/json

Json with the values to be used to create a new record \n Example:

{"NAME":"Dana", "EMAIL":"support@danaconnect.com"}
object

Responses

Request samples

Content type
application/json

Request sent to a contact defined in the JSON

{
  • "NAME": "Dana",
  • "EMAIL": "support@danaconnect.com"
}

Response samples

Content type
application/json
Example
Successful Request
Successful Request
Unsuccessful Request

Result of a successful request

{
  • "wsResult": {
    }
}

Start Conversation with recordUID (idRow)

Starts a conversation with a record identified by recordUID (idRow)

Authorizations:
basicAuth
path Parameters
conversationID
required
integer <int32> >= 1

Conversation Id to be started

Example: 200897
idRow
required
integer <int32> >= 1

Record Id in the Contact List

Example: 6
header Parameters
X-DEBUG
integer <int32> [ 0 .. 1 ]
Default: 0

Header that activates debug mode of conversations

Example: 1
Request Body schema: application/json

JSON with the values to be used to update the record
Example:

{"PHONE_NUMBER":"+19546441233","RECEIPT_FILE":"s3:\/\/Receipt\/receipt-example.pdf"}
object

Responses

Request samples

Content type
application/json

JSON with the values to be used to update the record

{
  • "PHONE_NUMBER": "+19546441233",
  • "RECEIPT_FILE": "s3://Receipt/receipt-example.pdf"
}

Response samples

Content type
application/json
Example
Successful Request
Successful Request
Unsuccessful Request

Result of a successful request

{
  • "wsResult": {
    }
}

Start Conversation List with the data provided

Starts a conversation with a batch of up to 10 new contacts with the given information

Authorizations:
basicAuth
path Parameters
conversationID
required
integer <int32> >= 1

Id of the conversation to be started

Example: 200897
header Parameters
X-DEBUG
integer <int32> [ 0 .. 1 ]
Default: 0

Header that activates debug mode of conversations

Example: 1
Request Body schema: application/json

JSON Array with different fields for each record to be created ( up to 10 new records )
Example:

[
{"LASTNAME":"MOLA","EMAIL":"954222233","ID_TYPE":"PASSPORT","NAME":"JOHN","GENDER":"M"},
{"LASTNAME":"BORDA","EMAIL":"939988777","ID_TYPE":"PASSPORT","NAME":"ROBERT","GENDER":"M"}]
Array ()
object

Responses

Request samples

Content type
application/json

JSON Array containing the records to be created

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json

Result of a successful request

[
  • {
    },
  • {
    }
]

ConversationAPI By ProjectID

ConversationAPI by ProjectID Endpoint

Start Conversation with the data provided using ProjectID

Starts a conversation with one new record using the data given in the JSON

Authorizations:
basicAuth
path Parameters
projectID
required
integer <int32> >= 1

Project Id to be started

Example: 101007
header Parameters
X-DEBUG
integer <int32> [ 0 .. 1 ]
Default: 0

Header that activates debug mode of conversations

Example: 1
Request Body schema: application/json

Json with the values to be used to create a new record
Example:

{"NAME":"Dana", "EMAIL":"support@danaconnect.com"}
object

Responses

Request samples

Content type
application/json

Request sent to a contact defined in the JSON

{
  • "NAME": "Dana",
  • "EMAIL": "support@danaconnect.com"
}

Response samples

Content type
application/json
Example
Successful Request
Successful Request
Unsuccessful Request

Result of a successful request

{
  • "wsResult": {
    }
}

DataRetrievalAPI

DataRetrieval Endpoint

Returns contact information

Multiple values are returned for each contact

Authorizations:
basicAuth
path Parameters
danaparam
required
string non-empty

Code 'dana' usually sent to external URLs

Example: 1KZK5BdVKDH6mKcAiXGMPh1KT3xpx2w
query Parameters
fields
string

String containing a list of requiered fields separated by comma ( , )

Example: fields=EMAIL,NAME,PHONE_NUMBER

Responses

Request samples 

curl -i -X GET \
-u <username@companycode>:<password>  \
'https://appserv.danaconnect.com/api/1.0/rest/conversation/data/:danaparam?fields=EMAIL,NAME,PHONE_NUMBER' \
-H 'Accept: application/json'

Response samples

Content type
application/json
Example
Successful Request
Successful Request
Invalid parameter in the request

Successful Result

{
  • "record": {
    },
  • "requestID": "5bc6bb89-82c7-4a2a-80a3-fbf5abedeee9"
}