Twitter DM

Using Twitter Direct Messages

Channel Identifier

In the API this channel can be referenced using: twitterDm

This identifier can be used in the rules array, and customBody sections.

Enabling the Twitter DM Channel

See our Twitter DM channel guide for more information on how to setup the channel for Twitter DM sending.

Sending to Twitter Users

The Omnichannel API supports sending text or media attachments to users, or use a custom body to specify more rich message options.

📘

Only a single conversation per user

Twitter DM only supports a single conversation between two parties.

There are the following possible ways to target customer for a message with Twitter DM and they are:

  • Profile Id - The users unique profile id
  • Twitter Id - A unique numeric identifier for a Twitter user
  • Twitter Username - The unique Twitter username for the user

We recommend using the Profile Id, as most conversations are started with an inbound Twitter DM message and we will automatically store and lookup the Twitter Id for you.

🚧

You can only message users who have opted in

A Twitter user must have opted in to communicate with you before you can send a DM message to them using one or more of the following:

  • they have send you a message already
  • be following you on Twitter
  • they have the option to allow DM’s from anyone enabled

See our Twitter DM channel guide for more information on how to help users to contact you via Twitter DM.

Sending using a Profile Id

You should pass the profileId in the to section of the send request to send using a profile id. We will automatically retrieve the Twitter Id for the user from the profile, which is usually obtained when a user sends an inbound message to you and automatically added to the profile for the user.

Sending using the Twitter Id

You should pass the twitterId in the to section of the send request to send using a Twitter id. The Twitter id is a long unique numeric identifier, but is passed as a string.

Sending using the Twitter Id

You should pass the twitterUserName in the to section of the send request to send using a Twitter username. The Twitter Username is unique Twitter username for the user without the leading @.

Where can I find a Twitter Id after they have opted in?

We automatically receive Twitter Ids as your users contact you and store their Twitter Id in the customers profile in the twitterId attribute.

In addition to storing the Twitter Id on the profile we will automatically retrieve the following details from Twitter:

Twitter Data ItemProfile fieldData type
Nametwitter.namestring
Twitter usernametwitterUsernamestring
Twitter IdtwitterIdstring
Profile picture URLtwitter.profile_image_url_httpsstring
Twitter descriptiontwitter.descriptionstring
Languagetwitter.langstring - 2 digit language identifier
Locationtwitter.locationstring
Timezonetwitter.time_zonestring
UTC Offsettwitter.utc_offsetstring
Twitter verified statustwitter.verifiedboolean
Twitter protected statustwitter.protectedboolean

This additional information is held in the twitter section of the users profile.

The following requests are examples of how to send using the Omnichannel API and Twitter DM:

{
  "to": {
    "profileId": "[email protected]"
  },
  "body": "My customer message via Twitter DM using a profile id",
  "rules": [
    "twitterDm"
  ]
}
{
  "to": {
    "twitterId": "11112223333444444"
  },
  "body": "My customer message via Twitter DM using explicit twitterId",  
  "rules": [
    "twitterDm"
  ]
}
{
  "to": {
    "twitterUserName": "acme"
  },
  "body": "My customer message via Twitter DM using explicit twitter username",  
  "rules": [
    "twitterDm"
  ]
}
{
  "title": "Your order has been dispatched",
  "to": {
    "profileId": "[email protected]"
  },
  "rules": [
    "twitterDm"
  ],
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Your order: ABC1245 has been dispatched."
    },
    {
      "type": "image/png",
      "url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png"
    }
  ]
}
{
  "to": {
    "twitterId": "11112223333444444",
    "phoneNumber": "441234123123"
  },
  "body": "My customer message using Branch to choose from Twitter DM and SMS",
  "rules": [
    "twitterDm",
    "sms"
  ]
}

Channel Options

This channel has no channel options.

Custom Body

Twitter DM is capable of sending many types of messages including:

The Omnichannel API automatically creates a text based Twitter DM message if you only define the body property when sending a message, or let us automatically create you a media message using Multi part messages. If you want to use some of the more advanced messaging features of Twitter DM you can if you use the customBody property and define a twitterDm object within it that complies with the Twitter DM API's message data object object as defined in the Twitter DM docs. Essentially you can pass any Twitter DM message event type you desire if you define this property.

Examples of sends using Twitter DM custom bodies are:

{
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Item Repaired, your return number: ABC1245 has been repaired and is being retuned to you"
    },
    {
      "type": "image/png",
      "url": "http://cdn.dnky.co/cpaas/images/laptop.png"
    }
  ],
  "rules": [
    "twitterDm"
  ]
}
{
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "customBody": {
    "twitterDm": {
      "text": "What's your favorite type of bird?",
      "quick_reply": {
        "type": "options",
        "options": [
          {
            "label": "Red Bird",
            "description": "A description about the red bird.",
            "metadata": "external_id_1"
          },
          {
            "label": "Blue Bird",
            "description": "A description about the blue bird.",
            "metadata": "external_id_2"
          }
        ]
      }
    }
  },
  "rules": [
    "twitterDm"
  ]
}
{
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "customBody": {
    "twitterDm": {
      "text": "Want to learn more about Comapi click on link below",
      "ctas": [
        {
          "type": "web_url",
          "label": "Show me the docs",
          "url": "https://docs.comapi.com/"
        },
        {
          "type": "web_url",
          "label": "Open the portal",
          "url": "https://portal.comapi.com/#/login"
        },
        {
          "type": "web_url",
          "label": "Where are you?",
          "url": "https://goo.gl/maps/gdi25vJi1Ny"
        }
      ]
    }
  },
  "rules": [
    "twitterDm"
  ]
}

Receipts and Inbounds

To receive feedback or inbound messages from Twitter DM sends please see the following:

Inbound Messages

Allows you to receive Twitter DM messages sent to your Twitter user. Messages are delivered to a URL of your choosing using the webhook system. See the Inbound event in the Message Events section for more details.

Receipts

If you need to to know the status of messages you've sent using one of our Omnichannel API, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts:

  • Sent
  • Read
  • Failed

🚧

No delivery receipts

Although Twitter DM supports read receipts there is no concept of a delivery receipt and therefore we will not report or generate webhook events for deliveries.