DIRECT_LINE_CALLS.md

Direct Line API calls

Create a conversation

API call

curl https://directline.botframework.com/v3/directline/conversations \
  -H "Authorization: Bearer <DIRECT_LINE_SECRET_KEY>" \
  -X POST

Response

• conversationId the resource ID to use for sending and receiving messages.
• token This is a JSON web token for conversation scoped API calls, you can continue to use the DIRECT_LINE_SECRET_KEY instead unless you have a reason to use tighter scoping.
• expires_in the number of seconds until the conversation scoped token expires. Always an hour as far as I can tell. There's a renewal endpoint somewhere.
• streamUrl the websocket URL to subscribe to for conversation events.

{
  "conversationId": "Fru3XFqaJjOILqgvgjjnF2-us",
  "token": "eyJhbGciOiJ...",
  "expires_in": 3600,
  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/Fru3XFqaJjOILqgvgjjnF2-us/stream?watermark=..."
}

Send an end-user message to a conversation

API call

curl https://directline.botframework.com/v3/directline/conversations/<CONVERSATION_ID>/activities \
  -H "Authorization: Bearer <DIRECT_LINE_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "from": { "id": "<WHATEVER_EXTERNAL_ID_FROM_YOUR_SYSTEM>", "name": "Stasi" },
    "text": "Hi from my custom app 👋",
    "channelData": {
      "channeltype": "custom",
      "conversationcontext": { "Workstream": "BYOC", "Priority": "Normal" },
      "customercontext": { "email": "[email protected]", "phonenumber": "15146666667" }
    }
  }' \
  -X POST

Response

• id the activity ID.

{
  "id": "Fru3XFqaJjOILqgvgjjnF2-us|0000001"
}

Fetch the conversation

API call

curl https://directline.botframework.com/v3/directline/conversations/<CONVERSATION_ID>/activities \
  -H "Authorization: Bearer <DIRECT_LINE_SECRET_KEY>"

Response

{
  "activities": [
    {
      "type": "message",
      "id": "Gp5WEZta8uN4CnMP6LiPxr-us|0000000",
      "timestamp": "2025-08-29T13:45:30.2441536Z",
      "serviceUrl": "https://directline.botframework.com/",
      "channelId": "directline",
      "from": {
        "id": "STASI",
        "name": "Stasi"
      },
      "conversation": {
        "id": "Gp5WEZta8uN4CnMP6LiPxr-us"
      },
      "text": "Hi from my custom app 👋"
    }
  ],
  "watermark": "0"
}