Conversation Management

When creating an app to manage Direct Messages, having context of where the user came from or what application was responsible for sending the message can be important information for managing the conversation. Having this context can help improve analytics or determine the next action your app should take. To provide this context the following is available in Direct Message event objects when applicable.

  • initiated_via provides the Twitter entity (Tweet or Welcome Message) that preceded the Direct Message in conversation.
  • source_app provides information about the Twitter app the authenticating account used to send the Direct Message.

initiated_via

When users communicate with businesses through Direct Messages, they may be guided by Welcome Messages or led to a private conversation via a Direct Message deeplink. In these cases, it can be important for developers to know if another object preceded the DM in conversation. For example, Initiated Via helps a customer service agent see the full conversation history or enable a bot developer to perform A/B testing of different welcome messages.

The initiated_via object in the Direct Message event object indicates the ID of the Twitter entity that directly preceded the DM in the sender’s context. Currently tweet_id and welcome_message_id may be included. The initiated_via object is only present if a Twitter entity directly preceded the DM.

initiated_via object

Property Description
initiated_via.tweet_id The ID of the Tweet with Direct Message Prompt the event was initiated from if one was used.
initiated_via.welcome_message_id The ID of the Welcome Message immediately preceding the event if one was used.

Note

Direct Messages are never referenced as an entity type under the “initiated_via” object. Developers should continue to rely on IDs for ordering Direct Message events.

Example Direct Message Event

The following Direct Message event was preceded by a Direct Message prompt from a Tweet or a Welcome Message was presented to the user.

{
  "type": "message_create",
  "id": "1234858592",
  "created_timestamp": "1392078023603",
  "initiated_via": {
    "tweet_id": "123456",
    "welcome_message_id": "456789"
  },
  "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": {
         ...
        }
      }
    }
  }
}

source_app

Some Twitter accounts may make use of more than one application to send Direct Messages — such as when a human social care app is used alongside a separate bot app to manage the same account. In these cases, it can be helpful for developers to know which app was used to send a given message.

The new source_app object will return this information for all DMs sent by an account. This object is included in the JSON payload for webhooks and REST endpoints. It is relevant on the read path only — Twitter automatically adds this information based on the app authentication used to post a DM. This value will not be returned in the response for POST events/new.json.

Note

This same pattern exists with Tweets with the source property, however the JSON structure is different. Please also note that this object will not be included for DMs received by an authenticating user and is only included for DMs sent by the authenticating user.

source_app object

Property Description
id The ID of the Twitter app used by the authenticating user to send the DM.
name The name of the Twitter app used by the authenticating user to send the DM.
url The URL of the Twitter app used by the authenticating user to send the DM.

Example for GET direct_messages/events/list.json

Notice that the source_app_id is included in the event object. Additional information can be found in the apps object.

{
  "event": {
    "type": "message_create",
    "id": "854103000570187779",
    "created_timestamp": "1492468998459",
    "message_create": {
      "target": {
        "recipient_id": "3340250004"
      },
      "sender_id": "51378538",
      "source_app_id": "268278",
      "message_data": {
        "text": "Hello",
        "entities": {
          "hashtags": [],
          "symbols": [],
          "user_mentions": [],
          "urls": []
        }
      }
    }
  }
  "apps": {
    "268278": {
      "id": "268278",
      "name": "Twitter Web Client",
      "url": "http://twitter.com"
    }
  }
}

Example for GET direct_messages/events/show.json

{
  "events": [
    {
      "type": "message_create",
      "id": "854103000570187779",
      "created_timestamp": "1492468998459",
      "message_create": {
        "target": {
          "recipient_id": "3340250004"
        },
        "sender_id": "51378538",
        "source_app_id": "268278",
        "message_data": {
          "text": "Hello",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "user_mentions": [],
            "urls": []
          }
        }
      }
    },
    {
      "type": "message_create",
      "id": "867807494898188291",
      "created_timestamp": "1495736404524",
      "message_create": {
        "target": {
          "recipient_id": "3340250004"
        },
        "sender_id": "51378538",
        "source_app_id": "9206597",
        "message_data": {
          "text": "World",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "user_mentions": [],
            "urls": []
          }
        }
      }
    },
  ],
  "apps": {
    "9206597": {
      "id": "9206597",
      "name": "BeeToSeaBiz TestApp Awesome",
      "url": "https://twitter.com/beetoseabiz"
    },
    "268278": {
      "id": "268278",
      "name": "Twitter Web Client",
      "url": "http://twitter.com"
    }
  }
}