Touchpoints API

Who can use this feature?

  • Global admins
  • Available on all plans

Use the Touchpoint API endpoints to create, delete, update and read touchpoints on accounts in Totango. 

Before you begin

  • You need your Totango API token key
  • For US services, please use https://api.totango.com
  • For EU services, please use https://api-eu1.totango.com 
  • Like all APIs, there is a global rate limit of 100 calls/minute for each token
  • Touchpoints API does not support HTML markup/formatting of touchpoints. (The API doesn't support HTML, but the Content header of the API does.)
  • JSON format is supported for API calls

Create a new touchpoint

Create a new touchpoint by POSTing touchpoint data to {US or EU api URL}/api/v3/touchpoints/. Post data should include the following:

{
  account_id: '0000',  
  content: 'This is the content of the touchpoint', 
  activity_type_id:  'escalation',  
  created_by: 'avon@barksdale-industries.org',
  create_date: 1461110400000,             // optional
  disable_sync: true                      // optional
  touchpointType: id (get it from the get request of types listed below).
  touchpoint_tags: Array of ids
  participantList: Array of Objects => [{userid: 'user1@totango.com'},{userid: 'user2@totango.com'}]
  subject: just text
}
  • account_id: The account’s ID in Totango
  • content: The content of the touchpoint. Up to 12K characters
  • activity_type_id: *optional* The Flow ID. To get the ID of a Flow use the /api/v3/activity-types endpoint as describe here.
  • created_by: *optional* The user email created the touchpoint. Totango will identify if this is a valid Totango user (and show his name if does) or external user (and show the email).
  • create_date: *optional* The timestamp in unix time (EPOCH) miliseconds format. The touchpoint will  registered at this time. Example: 1461110400000. If not provided, the current timestamp will be used. 
  • disable_sync: *optional*. Set to true if you do not want Totango to sync this touchpoint with Salesforce.com or other 3rd party systems. This is useful if you are pushing this touchpoint via API from a SFDC Trigger or Workflow, and do not want Totango to create a new SFDC Activity object as a result. 
  • touchpointType: *optional*. Set to the id of the type by using the get request below
  • touchpoint_tags: *optional*. Set to the array of id's based on the request below
  • participantList: *optional*. Set to array of objects in this format [{userId: unique ID of user in Totango},{userId: unique ID of user in Totango}]
  • subject: *optional*. Set to a text for the subject line

cURL

curl --data 'account_id=0000&content=this+is+a+curl+test&activity_type_id=escalation&user_id=YOUR-TOTANGO-USER&create_date=1479081600000' --header 'app-token:YOUR-TOKEN-HERE' 'https://app.totango.com/api/v3/touchpoints/'

JavaScript

const TOTANGO_TOKEN = 'PUT YOUR TOKEN HERE';
const TOTANGO_USER = 'PUT YOUR TOTANGO USER (email address) HERE';

// use: npm install request 
var request = require("request"); 

request.post("https://api.totango.com/api/v3/touchpoints/", {
    headers: {
		'app-token': TOTANGO_TOKEN
    },
    form: {
		account_id: '0000', // replace with an account_id on your system
                content: 'this is a test escalation',
                activity_type_id: 'escalation',
		user_id: TOTANGO_USER,
		create_date: Date.now() - (1000 * 60 * 60 * 48), 
    }
}, (error, response, body) => {
            // handle success / failure ... 
            console.log(response.statusCode);
});

The touchpoint will be created under the name of the user whose token was used to make the call.

Update an existing touchpoint

Update an existing touchpoint by sending PUT touchpoint data request to {US or EU api URL}/api/v3/touchpoints/{note_id}. The request data should include the following:

{
  note_id: 47124,
  event_id: '4a0c13edzfacez3038zbb46z85f97f04238f',
  account_id: '0000',  
  content: 'This is the content of the touchpoint', 
  activity_type_id:  'escalation',  
  created_by: 'avon@barksdale-industries.org',
  create_date: 1461110400000,             // optional
  disable_sync: true                      // optional
  touchpointType: id (get it from the get request of types listed below).
  touchpoint_tags: Array of ids
  participantList: Array of Objects => [{userid: 'user1@totango.com'},{userid: 'user2@totango.com'}]
  subject: just text
}
  • note_id: Returned as part of the touchpoint creation response or using the GET method (detailed below)
  • event_id: Returned as part of the touchpoint GET method (detailed below)
  • account_id: The account’s ID in Totango
  • content: The content of the touchpoint. Up to 12K characters
  • activity_type_id: *optional* The Flow ID. To get the ID of a Flow use the /api/v3/activity-types endpoint as describe here.
  • created_by: *optional* The user email created the touchpoint. Totango will identify if this is a valid Totango user (and show his name if does) or external user (and show the email).
  • create_date: *optional* The timestamp in unix time (EPOCH) miliseconds format. The touchpoint will  registered at this time. Example: 1461110400000. If not provided, the current timestamp will be used. 
  • disable_sync: *optional*. Set to true if you do not want Totango to sync this touchpoint with Salesforce.com or other 3rd party systems. This is useful if you are pushing this touchpoint via API from a SFDC Trigger or Workflow, and do not want Totango to create a new SFDC Activity object as a result. 
  • touchpointType: *optional*. Set to the id of the type by using the get request below
  • touchpoint_tags: *optional*. Set to the array of id's based on the request below
  • participantList: *optional*. Set to array of objects in this format [{userId: unique ID of user in Totango},{userId: unique ID of user in Totango}]
  • subject: *optional*. Set to a text for the subject line

CURL

curl --data 'account_id=0000&content=this+is+a+curl+test&activity_type_id=escalation&user_id=YOUR-TOTANGO-USER&create_date=1479081600000' --header 'app-token:YOUR-TOKEN-HERE' --location --request PUT 'https://app.totango.com/api/v3/touchpoints/47124'

JavaScript

const TOTANGO_TOKEN = 'PUT YOUR TOKEN HERE';
const TOTANGO_USER = 'PUT YOUR TOTANGO USER (email address) HERE';

// use: npm install request 
var request = require("request"); 

request.put("https://api.totango.com/api/v3/touchpoints/47124", {
    headers: {
		'app-token': TOTANGO_TOKEN
    },
    form: {
		note_id: '47124', //replace with the note Id retrieved.
                account_id: '0000', // replace with an account_id on your system
                content: 'this is a test escalation',
                activity_type_id: 'escalation',
		user_id: TOTANGO_USER,
		create_date: Date.now() - (1000 * 60 * 60 * 48), 
    }
}, (error, response, body) => {
            // handle success / failure ... 
            console.log(response.statusCode);
});

Retrieve events per account

Touchpoints are stored as events in an account’s timeline and can be retrieved using the /v2/events/ endpoint.

GET {US or EU api URL}/api/v2/events/?account_id={account_id} to retrieve all events registered on the timeline of account_id.

Returns a JSON array of events,  in the following format. Use the type property to distinguish between touchpoints (type=’note’), tasks (type=’task’), and other items.  

{
        "id": "4a0c13edzfacez3038zbb46z85f97f04238f",
        "timestamp": 1578588991000,
        "type": "note",
        "account": {
            "id": "7987"
        },
        "is_new": null,
        "note_content": {
            "text": " This is a touchpoint body\n",
            "totango_user": {
                "user_name": "user@totango.com"
            },
            "note_id": 47124
        },
        "properties": {
            "customers_visibility": false,
            "activity_type_id": "disabled_1576166402106",
            "containsFormatting": "true",
            "subject": "",
            "meeting_type": "0af9272e-a055-441e-ae10-f4223a3e0ab8",
            "touchpoint_tags": [
                "450ea17a-0e76-418f-a4ec-8ae7b16b3b85"
            ]
        }
    },

For brevity, we are only showing an event of type “note”, which is the internal name used for a touchpoint. Other event types include “task” and “alert”.

The text of the touchpoint is accessible in note_content.text. The user who authored the touchpoint is available under note_content.totango_user.user_name (email address as registered in Totango).

properties.activity_type_id contains the ID of the Flow associated with this touchpoint.

Use note_content.note_id and id fields to delete the touchpoint (see below).

CURL

curl -X GET --header 'app-token:YOUR-TOKEN-HERE' 'https://api.totango.com/api/v2/events?account_id='

JavaScript

'use strict'
// Available in your user profile on Totango
var TOTANGO_TOKEN = 'YOUR-TOKEN-HERE';


// use: npm install request 
var request = require("request"); 

var account_id = 000; // the account id you want the touchpoints for

request.get("https://api.totango.com/api/v2/events/?account_id=" + account_id, {
 headers: {
			'app-token': TOTANGO_TOKEN
		}
},
 function(error, response, body) {
            // handle success / failure ... 

        let results = JSON.parse(body);
        // filter touchpoints only (type === note)
        const touchpoints = results.filter((o) => o.type === "note"); 
        console.log(touchpoints);
});

Retrieve the list of activity types (touchpoint type) and reasons (touchpoint reason)

To understand what meeting_type id is: you can call {US or EU api URL}/api/v3/touchpoint-types/ with your token you will get a map all of types (id -> name)

curl --location --request GET 'https://api.totango.com/api/v3/touchpoint-types/'
--header 'app-token: <your token here>'

To understand what reasons_id is: you can call {US or EU api URL}/api/v3/touchpoint-tags/ with your token and you will get a map all of reasons (id -> name)

curl --location --request GET 'https://api.totango.com/api/v3/touchpoint-tags/'
--header 'app-token: <your token here>'

Remove a touchpoint

To remove a touchpoint from an account, use an HTTP DELETE command with the following structure

DELETE {US or EU api URL}/api/v3/touchpoints/{note_id}

adding the event_id  in the post data

In order to delete a touchpoint, you need both its note_id and event_id, as retrieved from the list of events (see Retrieving the list of touchpoints, above). The note_id is used in the DELETE URL, and the event_id should be posted as data into the request.

CURL

curl -X DELETE  --data 'event_id=3963e754zccd4z3bd8zb563z0dd2d938ddbe' --header 'app-token:your-token-goes-here' 'https://app.totango.com/api/v3/touchpoints/292920'

JavaScript

// Available in your user profile on Totango
var TOTANGO_TOKEN = 'YOUR-TOTANG-TOKEN';


// use: npm install request 
var request = require("request"); 

// note_id and event_id should be retrieved from the account’s v2/events/ api
var note_id = ‘9999’;
var event_id = ‘6a8c7f9cz143fz3242zb0b2z3f8903f9740f’;

request.delete("https://api.totango.com/api/v3/touchpoints/" + note_id, {
 headers: {
			'app-token': TOTANGO_TOKEN
		},
 form: {
            event_id: event_id
        }
},
 function(error, response, body) {
            // handle success / failure ... 
        
        console.log(body);
});

Retrieve the list of flow IDs

To set the flow of a touchpoint, use the actvitiy_type_id field as shown above. In order to get the list of valid ID values, you can use the {US or EU api URL}/api/v3/activity-types  endpoint.

curl --location --request GET 'https://api.totango.com/api/v3/activity-types/'
--header 'app-token: <your token here>'

will return the following data structure:

{
   "renewal": {
      "activity_type_id": "renewal",
      "display_name": "Renewal",
      "num_of_activities_assign_to": 0,
      "icon_class": "icon-dollar",
      "system_type": true,
      "default_type": false,
      "disabled": false
},
   "support": {
      "activity_type_id": "support",
      "display_name": "Support",
      "num_of_activities_assign_to": 0,
      "icon_class": "icon-lifebouy",
      "system_type": true,
      "default_type": false,
      "disabled": false
}, 
   { ... }
}

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request