Documentation

Twitter Integration with REST API

Getting Started

If you’re building a Twitter DM bot, here are ome useful resources at Twitter:

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Integrate the REST API

There are a few integration points as outlined below.

Note
Overall, there are a few pieces of data that we need you to pull out of the Twitter JSON, and then the rest of the Twitter JSON goes in “platformJson”

1. When your bot sends a message with buttons


From the Twitter Example, when your bot sends a message, it will look like something like this:

page image

Post to the following endpoint:

https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’

The data to POST should pass the following data:

{
"text": "What's your favorite type of bird?",
"userId": "1234858592",
"buttons": [
{
"id": "1",
"label": "Red Bird",
"value": "external_id_1"
},
{
"id": "2",
"label": "Blue Bird",
"value": "external_id_2"
}
],
"platformJson": {
"direct_message_events": [
{
"type": "message_create",
"id": "1234858585",
"created_timestamp": "1392078023507",
"message_create": {
"target": {
"recipient_id": "3805104374"
},
"sender_id": "1234858592",
"source_app_id": "8829219",
"message_data": {
"text": "What's your favorite type of bird?",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": []
},
"quick_reply": {
"type": "options",
"options": [
{
"label": "Red Bird",
"metadata": "external_id_1"
},
{
"label": "Blue Bird",
"metadata": "external_id_2"
},
{
"label": "Black Bird",
"metadata": "external_id_3"
},
{
"label": "White Bird",
"metadata": "external_id_4"
}
]
},
"attachment": {
"type": "media",
"media": {}
}
}
}
}
],
"users": {
"1234858592": {
"id": "1234858592",
"created_timestamp": "1415320482361",
"name": "TwitterDev",
"screen_name": "TwitterDev",
"location": "Internet",
"description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them",
"protected": false,
"verified": true,
"followers_count": 440643,
"friends_count": 1534,
"statuses_count": 2837,
"profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
},
"3805104374": {
"id": "3805104374",
"created_timestamp": "1449607341142",
"name": "Furni",
"screen_name": "furni",
"location": "San Francisco, CA",
"description": "Furni is Twitter's example company to showcase new developer features.",
"protected": false,
"verified": false,
"followers_count": 297,
"friends_count": 7,
"statuses_count": 1,
"profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
}
},
"apps": {
"8829219": {
"id": "8829219",
"name": "Furni",
"url": "https://twitter.com/furni"
}
}
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"text":"Whats your favorite type of bird?","userId":"1234858592","buttons":[{"id":"1","label":"Red Bird","value":"external_id_1"},{"id":"2","label":"Blue Bird","value":"external_id_2"}],"platformJson":{"direct_message_events":[{"type":"message_create","id":"1234858585","created_timestamp":"1392078023507","message_create":{"target":{"recipient_id":"3805104374"},"sender_id":"1234858592","source_app_id":"8829219","message_data":{"text":"What'"'"'s your favorite type of bird?","entities":{"hashtags":[],"symbols":[],"urls":[],"user_mentions":[]},"quick_reply":{"type":"options","options":[{"label":"Red Bird","metadata":"external_id_1"},{"label":"Blue Bird","metadata":"external_id_2"},{"label":"Black Bird","metadata":"external_id_3"},{"label":"White Bird","metadata":"external_id_4"}]},"attachment":{"type":"media","media":{}}}}}],"users":{"1234858592":{"id":"1234858592","created_timestamp":"1415320482361","name":"TwitterDev","screen_name":"TwitterDev","location":"Internet","description":"Developer and Platform Relations @Twitter. We are developer advocates. We can'"'"'t answer all your questions, but we listen to all of them","protected":false,"verified":true,"followers_count":440643,"friends_count":1534,"statuses_count":2837,"profile_image_url":"http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"},"3805104374":{"id":"3805104374","created_timestamp":"1449607341142","name":"Furni","screen_name":"furni","location":"San Francisco, CA","description":"Furni is Twitter'"'"'s example company to showcase new developer features.","protected":false,"verified":false,"followers_count":297,"friends_count":7,"statuses_count":1,"profile_image_url":"http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"}},"apps":{"8829219":{"id":"8829219","name":"Furni","url":"https://twitter.com/furni"}}}}'
'https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

2. When your bot receives a message


From the Twitter Example, when your bot sends a message, it will look like something like this:

page image

Post to the following endpoint:

https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’

The data to POST should pass the following data:

{
"text": "Blue Bird",
"userId": "1234858592",
"platformJson": {
"direct_message_events": [
{
"type": "message_create",
"id": "1234858589",
"created_timestamp": "1392078023603",
"message_create": {
"target": {
"recipient_id": "1234858592"
},
"sender_id": "3805104374",
"source_app_id": "268278",
"message_data": {
"text": "Blue Bird",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": []
},
"quick_reply_response": {
"type": "options",
"metadata": "external_id_2"
},
"attachment": {
"type": "media",
"media": {}
}
}
}
}
],
"users": {
"1234858592": {
"id": "1234858592",
"created_timestamp": "1415320482361",
"name": "TwitterDev",
"screen_name": "TwitterDev",
"location": "Internet",
"description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them",
"protected": false,
"verified": true,
"followers_count": 440643,
"friends_count": 1534,
"statuses_count": 2837,
"profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
},
"3805104374": {
"id": "3805104374",
"created_timestamp": "1449607341142",
"name": "Furni",
"screen_name": "furni",
"location": "San Francisco, CA",
"description": "Furni is Twitter's example company to showcase new developer features.",
"protected": false,
"verified": false,
"followers_count": 297,
"friends_count": 7,
"statuses_count": 1,
"profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
}
},
"apps": {
"268278": {
"id": "268278",
"name": "Twitter Web Client",
"url": "http://twitter.com"
}
}
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"text":"Blue Bird","userId":"1234858592","platformJson":{"direct_message_events":[{"type":"message_create","id":"1234858589","created_timestamp":"1392078023603","message_create":{"target":{"recipient_id":"1234858592"},"sender_id":"3805104374","source_app_id":"268278","message_data":{"text":"Blue Bird","entities":{"hashtags":[],"symbols":[],"urls":[],"user_mentions":[]},"quick_reply_response":{"type":"options","metadata":"external_id_2"},"attachment":{"type":"media","media":{}}}}}],"users":{"1234858592":{"id":"1234858592","created_timestamp":"1415320482361","name":"TwitterDev","screen_name":"TwitterDev","location":"Internet","description":"Developer and Platform Relations @Twitter. We are developer advocates. We cant answer all your questions, but we listen to all of them","protected":false,"verified":true,"followers_count":440643,"friends_count":1534,"statuses_count":2837,"profile_image_url":"http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"},"3805104374":{"id":"3805104374","created_timestamp":"1449607341142","name":"Furni","screen_name":"furni","location":"San Francisco, CA","description":"Furni is Twitter'"'"'s example company to showcase new developer features.","protected":false,"verified":false,"followers_count":297,"friends_count":7,"statuses_count":1,"profile_image_url":"http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"}},"apps":{"268278":{"id":"268278","name":"Twitter Web Client","url":"http://twitter.com"}}}}'
'https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE'

3. When your bot sends a text message out


When your bot sends a message, POST to the following endpoint:

https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’

The data to POST should pass the following data:

{
"text": "Just a normal text DM out.",
"userId": "1234858592",
"platformJson": {
"direct_message_events": [
{
"type": "message_create",
"id": "1244858585",
"created_timestamp": "1492078023507",
"message_create": {
"target": {
"recipient_id": "3805104374"
},
"sender_id": "1234858592",
"source_app_id": "8829219",
"message_data": {
"text": "Just a normal text DM out.",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": []
},
"attachment": {
"type": "media",
"media": {}
}
}
}
}
],
"users": {
"1234858592": {
"id": "1234858592",
"created_timestamp": "1415320482361",
"name": "TwitterDev",
"screen_name": "TwitterDev",
"location": "Internet",
"description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them",
"protected": false,
"verified": true,
"followers_count": 440643,
"friends_count": 1534,
"statuses_count": 2837,
"profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
},
"3805104374": {
"id": "3805104374",
"created_timestamp": "1449607341142",
"name": "Furni",
"screen_name": "furni",
"location": "San Francisco, CA",
"description": "Furni is Twitter's example company to showcase new developer features.",
"protected": false,
"verified": false,
"followers_count": 297,
"friends_count": 7,
"statuses_count": 1,
"profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
}
},
"apps": {
"8829219": {
"id": "8829219",
"name": "Furni",
"url": "https://twitter.com/furni"
}
}
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"text":"Just a normal text DM out.","userId":"1234858592","platformJson":{"direct_message_events":[{"type":"message_create","id":"1244858585","created_timestamp":"1492078023507","message_create":{"target":{"recipient_id":"3805104374"},"sender_id":"1234858592","source_app_id":"8829219","message_data":{"text":"Just a normal text DM out.","entities":{"hashtags":[],"symbols":[],"urls":[],"user_mentions":[]},"attachment":{"type":"media","media":{}}}}}],"users":{"1234858592":{"id":"1234858592","created_timestamp":"1415320482361","name":"TwitterDev","screen_name":"TwitterDev","location":"Internet","description":"Developer and Platform Relations @Twitter. We are developer advocates. We cant answer all your questions, but we listen to all of them","protected":false,"verified":true,"followers_count":440643,"friends_count":1534,"statuses_count":2837,"profile_image_url":"http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"},"3805104374":{"id":"3805104374","created_timestamp":"1449607341142","name":"Furni","screen_name":"furni","location":"San Francisco, CA","description":"Furni is Twitter'"'"'s example company to showcase new developer features.","protected":false,"verified":false,"followers_count":297,"friends_count":7,"statuses_count":1,"profile_image_url":"http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png","profile_image_url_https":"https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"}},"apps":{"8829219":{"id":"8829219","name":"Furni","url":"https://twitter.com/furni"}}}}'
'https://tracker.dashbot.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'