Dimension Labs API & Integrations

Twitter Direct Messages

Twitter Direct Messages enable private user conversations. Analyzing these messages can provide insights into customer feedback and queries.

Welcome to the Twitter documentation for Dimension! Integrating DImension into your Twitter DM bot is quick and easy.

If you have any questions, comments, or suggestions, please feel free to contact us.

Node Integration

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).twitter;

Whenever your bot sends, or receives data, log to Dimension

Message Format

You can send the following fields:

  • text – string – (required)
  • userId – string – (required) – should be the SAME userId for both incoming
    and outgoing messages this is NOT the bot’s user ID
  • intent – object – (optional)
    • name – string
    • inputs – array
      • input – object
        • name – string
        • value – string
  • images – array – (optional)
    • image – object
      • url – string
  • buttons – array – (optional)
    • button – object
      • id – string
      • label – string
      • value – string
  • postback – object (optional)
    • buttonClick – object
      • buttonId – string
  • platformJson – object (optional) – send ALL of your platform-specific
    JSON here. It will be available for viewing in your transcripts.

Log whenever your webhook is called

const messageForDimension = {
  "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"
      }
    }
  }
};
dimension.logIncoming(messageForDimension);

Whenever you send a message, log the response

const messageForDimension = {
  "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"
      }
    }
  }
};
dimension.logOutgoing(messageForDimension);

Example

View sample code.

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:

Post to the following endpoint:

https://tracker.dimensionlabs.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’ and to replace API_KEY_HERE with your api key.

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.dimensionlabs.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

2. When your bot receives a message

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

Post to the following endpoint:

https://tracker.dimensionlabs.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’ and to replace API_KEY_HERE with your api key.

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.dimensionlabs.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’ and to replace API_KEY_HERE with your api key.

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.dimensionlabs.io/track?platform=twitter&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.