Twitter Direct Messages

Our business messaging API supports sending and receiving Twitter direct messages.

Being able to send Twitter direct messages requires requesting access via the Channels portal. Without onboarding with Twitter via the portal, you can not make use of this part of the API.

Fact sheet

🚧

Note

Only non-animated webp files are supported by Twitter

Onboarding

Onboarding is done via our Channels portal. Via our portal, you are redirected to the authorization page of Twitter. On this page you will need to authorize our Twitter app, called CM Business Messaging API to send and receive Direct Messages on behalf of your Twitter account.

Business rules

Sending Twitter DMs using the CM Business Messaging API also requires you to adhere to the Twitter rules.

An extended set of rules and policies for Twitter messages can be found here.

It is allowed to have multiple Twitter accounts under one CM.com account.

Considerations

Note that in case of Twitter, the Twitter account that is used for sending messages is also still available in the regular Twitter app, from the Twitter website and from other 3rd party Twitter apps. Our API only has permissions to send on behalf of the Twitter account, but it's not exclusively in control of that Twitter account.

This means that it will be possible to send messages using Twitter as well as using our API, and that might lead to situations where the API will relay replies to messages you sent via the Twitter app or website.

In those cases it will seem like messages are missing from a conversation when you use both ways of communicating with your end-users.

Our recommendation is to use the API exclusively for these Twitter accounts, and not switch between the Twitter app or website and the API, because the API won't "know" about the messages you sent using the app or website, but it will receive the replies to those messages.

prerequisites

In your Twitter account, make sure you have enabled "Receive messages from anyone", found under Settings...Privacy and safety...Receive messages from anyone. If you don't enable this, end-users won't be able to message you and start a conversation.

There are two ways you can start a conversation with a Twitter end-user yourself;

• if the end-user follows your Twitter account.

• if the end-user has enabled "Receive messages from anyone"

In other cases the only way to start a Twitter conversation with end-users is when the end-user starts the conversation by sending you an initial message.

When a message is received from an end-user, you may send up to 5 messages in response within a 24 hour window. Each message received resets the 24 hour window and the 5 allotted messages. Sending a 6th message within a 24 hour window or sending a message outside of a 24 hour window will count towards rate-limiting.

Sending messages

Unlike other channels, Twitter does not use telephone numbers as identifiers for sender (from) and recipient (to.number), instead it uses so called "snowflakes", which are unique identifiers of the twitter accounts (e.g. the Twitter account @cmchanneldev has the snowflake 1263071591262494721).

The snowflake is a 64-bit unsigned integer, and is visible in the CM.com platform as the userid under channels...Twitter.

Display order

If you send a message including both an image and some text, Twitter will display this as one entity, always placing the text below the image, and “joining” the two visually.

It is possible to have the text above the image by sending two seperate conversations in a single API call; Twitter will then display them in order, but the text is not visually joined with the image.

See the Direct message with text and image example.

Receiving messages / Inbound flow

Since Twitter Direct Messaging is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of incoming messages. Note that for Twitter you need to set up your webhook API in the Channels app, not in the Gateway app.

Examples

Please note that currently we only support snowflakes when sending and receiving Twitter direct messages. An upcoming version of the API might also allow for using Twitter handles, but please note that a Twitter user may change their handle at any point in time, while the Twitter snowflake will remain the same for each individual account. Therefore, we would recommend using snowflakes as identifiers to prevent problems matching users to messages in your system.

Direct message with plain text contents

The example below will send a simple text-only Twitter direct message.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your snowflake",
                "to": [
                    {
                        "number": "Recipients Snowflake"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Twitter"],
                "body": {
                    "type": "auto",
                    "content": "CM.com - Be part of it."
                }
            }
        ]
    }
}

Direct message with text and image

In the example below we send a simple rich content message that contains both text and an image that Twitter will display as one entity. An explanation on how to send rich content messages in general can be found in the rich content description.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your snowflake",
                "to": [
                    {
                        "number": "Recipients Snowflake"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Twitter"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "conversational-commerce.jpg",
                                "mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
                                "mimeType": "image/jpeg"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with reply suggestion

In the example below we send a rich content message that contains a text and some reply suggestions. An explanation on reply suggestions can be found under Suggestions/Features under Rich Content

NOTE: Twitter only supports suggestions with "action": "Reply"

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your snowflake",
                "to": [
                    {
                        "number": "Recipients Snowflake"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Twitter"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "Hi, what can I do for you?",
                            "suggestions": [
                                {
                                    "action": "Reply",
                                    "label": "Create an appointment"
                                },
                                {
                                    "action": "Reply",
                                    "label": "Change my appointment"
                                },
                                {
                                    "action": "Reply",
                                    "label": "Cancel my appointment"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}