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:

ConversationAPI

ConversationAPI Endpoint

Start Conversation List

Starts a conversation with the preloaded list

SecuritybasicAuth
Request
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
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

post/conversation/{conversationID}/start/list
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
application/json

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

SecuritybasicAuth
Request
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
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

post/conversation/{conversationID}/start/data
Request samples
application/json

Request sent to a contact defined in the JSON

{
  • "NAME": "Dana",
  • "EMAIL": "support@danaconnect.com"
}
Response samples
application/json

Result of a successful request

{
  • "wsResult": {
    }
}

Start Conversation with recordUID (idRow)

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

SecuritybasicAuth
Request
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
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

post/conversation/{conversationID}/start/{idRow}
Request samples
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
application/json

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

SecuritybasicAuth
Request
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 ([ 1 .. 10 ] items)
object
Responses
200

Successful Request

400

Request Internal Error

401

Unauthorized User

409

Illegal Argument

post/conversation/{conversationID}/start/list/data
Request samples
application/json

JSON Array containing the records to be created

[
  • {
    },
  • {
    }
]
Response samples
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

SecuritybasicAuth
Request
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
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

post/conversation/ProjectID/{projectID}/start/data
Request samples
application/json

Request sent to a contact defined in the JSON

{
  • "NAME": "Dana",
  • "EMAIL": "support@danaconnect.com"
}
Response samples
application/json

Result of a successful request

{
  • "wsResult": {
    }
}

DataRetrievalAPI

DataRetrieval Endpoint

Returns contact information

Multiple values are returned for each contact

SecuritybasicAuth
Request
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
200

Successful Request

400

Request Internal Error

401

Unauthorized User

409

Illegal Argument

get/conversation/data/{danaparam}
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
application/json

Successful Result

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