Conversation API (2.0)

Download OpenAPI specification:Download

DANAConnect Support: support@danaconnect.com URL: https://www.danaconnect.com License: Apache 2.0 Terms of Service

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.

DANAConnect Developer Portal - Complete API Documentation and Guides

Considerations Prior to Using the API

  • The company that is going to use the API must have valid client credentials in the DANAConnect platform.
  • For security reasons, the user who is going to use the API must have a special scope. Your DANAConnect Account Manager must ensure that this scope is enabled.
  • This API works on Conversations (flows) that have previously been created and are active in the platform. This means you must have the Conversation ID (conversationID) for this flow.

What is the Conversation ID?

The conversation identification number in DANAConnect can be found on the activation reports page for each flow inside the Conversation Manager. Important: Every time a conversation is reactivated, a new Conversation ID will be generated.

Required Field Codes

You must have the codes of the required fields in the database used with this conversation. For example, Conversation with ID (123456) would require:

  • 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.

Here is a video explaining how to find the conversation ID:

ConversationAPI

Endpoints for starting and managing conversation workflows. Use these endpoints to trigger automated communication flows with contacts, either individually or in batches.

Start Conversation with recordUID (rowId)

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

Securityoauth2
Request
path Parameters
conversationId
required
integer <int32>

Unique identifier of the conversation workflow to start

Example: 12345
rowId
required
integer <int32>

Record UID (unique identifier) of the existing contact record

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

Header that activates debug mode of conversations

Example: 1
Request Body schema: application/json

Optional JSON object with additional field values to merge with the existing record

object

Dynamic key-value pairs where keys are field codes configured in the conversation workflow

Responses
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

post/conversation/{conversationId}/start/{rowId}
Request samples
application/json

Override fields example

{
  • "EMAIL": "updated@example.com"
}
Response samples
application/json

Result of a successful request

{
  • "wsResult": {
    }
}

Start Conversation List

Starts a conversation with the preloaded list

Securityoauth2
Request
path Parameters
conversationId
required
integer <int32>

Unique identifier of the conversation workflow to start

Example: 12345
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/2.0/rest/conversation/${conversationId}/start/list`, 
        { 
            method: 'POST', 
            headers: { 
                'X-DEBUG': '0', 
                Authorization: 'Bearer <access_token>' 
            } 
        } 
    ); 
    const data = await resp.text(); 
    console.log(data); 
} 

makeRequest()
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 100 new contacts with the given information

Securityoauth2
Request
path Parameters
conversationId
required
integer <int32>

Unique identifier of the conversation workflow to start

Example: 12345
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 of contact objects (max 100 items)

Array
object

Dynamic key-value pairs where keys are field codes configured in the conversation workflow

Responses
200

Successful Request

400

Request Internal Error

401

Unauthorized User

409

Illegal Argument

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

Batch contacts example

[
  • {
    },
  • {
    }
]
Response samples
application/json

Result of a successful request

[
  • {
    },
  • {
    }
]

Start Conversation with the data provided

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

Securityoauth2
Request
path Parameters
conversationId
required
integer <int32>

Unique identifier of the conversation workflow to start

Example: 12345
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 object with field codes as keys and their values

object

Dynamic key-value pairs where keys are field codes configured in the conversation workflow

Responses
200

Successful Request

400

Request Internal Error

401

Unauthorized user

409

Illegal Argument

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

Contact data example

{
  • "EMAIL": "john.doe@example.com",
  • "NAME": "John Doe",
  • "PHONE_NUMBER": "+34659000000"
}
Response samples
application/json

Result of a successful request

{
  • "wsResult": {
    }
}

Get Conversation Configuration Fields

Retrieves all configured field names for a specific conversation workflow

Securityoauth2
Request
path Parameters
conversationId
required
integer <int64>

Unique identifier of the conversation workflow to start

Example: 12345
Responses
200

Successful Request

400

Request Internal Error

401

Unauthorized User

404

Conversation Not Found

get/conversation/{conversationId}/config
Request samples 
Response samples 
application/json
Successful Result


{
  • "wsResult": {
    }
}
ConversationAPI By ProjectID
Alternative endpoints that use ProjectID instead of ConversationID. Useful when you have project-level access rather than specific conversation IDs.


Start Conversation with the data provided using projectId
Starts a conversation with one new record using the data given in the JSON


Securityoauth2 
Request 
path Parameters
projectId
required
integer <int32> 
Project identifier (alternative to idConversation for project-based access)


 
 Example:  98765
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 object with field codes as keys and their values


object
Dynamic key-value pairs where keys are field codes configured in the conversation workflow


 
Responses 
200
Successful Request


400
Request Internal Error


401
Unauthorized user


409
Illegal Argument


post/conversation/ProjectID/{projectId}/start/data
Request samples 
application/json
{
  • "EMAIL": "john.doe@example.com",
  • "NAME": "John Doe",
  • "PHONE_NUMBER": "+34659000000",
  • "CUSTOM_FIELD": "custom value"
}
Response samples 
application/json
Result of a successful request


{
  • "wsResult": {
    }
}
Get ProjectId Configuration Fields
Retrieves all configured field names for a specific ProjectId workflow


Securityoauth2 
Request 
path Parameters
projectId
required
integer <int64> 
Project identifier (alternative to idConversation for project-based access)


 
 Example:  12345
Responses 
200
Successful Request


400
Request Internal Error


401
Unauthorized User


404
Conversation Not Found


get/conversation/ProjectID/{projectId}/config
Request samples 
Response samples 
application/json
Successful Result


{
  • "wsResult": {
    }
}
DataRetrievalAPI
Endpoints for retrieving contact data and conversation field configurations. Use these to fetch stored contact information or discover required fields.


Returns contact information
Multiple values are returned for each contact


Securityoauth2 
Request 
path Parameters
danaParam
required
string
Dana parameter identifier used to retrieve contact data


 
 Example:  abc123-def456-ghi789
query Parameters
fieldList
string
Comma-separated list of field codes to retrieve. If omitted, all fields are returned.


 
 Example:  fieldList=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 \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/json' \
'https://appserv.danaconnect.com/api/2.0/rest/conversation/data/:danaparam?fields=EMAIL,NAME,PHONE_NUMBER' 
Response samples 
application/json
Successful Result


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