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 Comapi for Twitter DM sending.

Sending to Twitter Users

Comapi 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 Comapi 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 Comapi 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 Comapi Profile Id

You should pass the profileId in the to section of the send request to send using a Comapi profile id. Comapi 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?

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

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

Twitter Data Item	Comapi Profile Identifier	Data type
Name	twitter.name	string
Twitter username	twitterUsername	string
Twitter Id	twitterId	string
Profile picture URL	twitter.profile_image_url_https	string
Twitter description	twitter.description	string
Language	twitter.lang	string - 2 digit language identifier
Location	twitter.location	string
Timezone	twitter.time_zone	string
UTC Offset	twitter.utc_offset	string
Twitter verified status	twitter.verified	boolean
Twitter protected status	twitter.protected	boolean

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

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

{
  "to": {
    "profileId": "dave@acme.com"
  },
  "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": "dave@acme.com"
  },
  "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 Comapi Enterprise Communications API automatically creates a text based Twitter DM message if you only define the body property when sending a message, or let Comapi 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/3rdparty/comapi/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 Comapi's 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 Enterprise Communications API, you can request that delivery receipts are forwarded to a URL of your choosing using Comapi's 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 Comapi will not report or generate webhook events for deliveries.

👍
Check out our quick starts...
Check out our quick starts for simple code examples of how to send with the "One" API