Initialize Conversation Keys

Initializes encryption keys for a Chat conversation. This is the first step before sending messages in a new 1:1 conversation.

For 1:1 conversations, provide the recipient’s user ID as the conversation_id. The server constructs the canonical conversation ID from the authenticated user and recipient.

The request body must contain the conversation key version and participant keys (the conversation key encrypted for each participant using their public key).

Workflow (1:1 conversation):

1. Generate a conversation key using the SDK
2. Encrypt the key for both participants using their public keys
3. Call this endpoint to register the keys
4. Send messages using POST /chat/conversations/{id}/messages

Authentication:

• Requires OAuth 1.0a User Context or OAuth 2.0 User Context
• Required scopes: tweet.read, users.read, dm.write

POST /2/chat/conversations/{id}/keys

Initialize Conversation Keys

cURL

curl --request POST \
  --url https://api.x.com/2/chat/conversations/{id}/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation_key_version": "<string>",
  "conversation_participant_keys": [
    {
      "encrypted_conversation_key": "<string>",
      "public_key_version": "<string>",
      "user_id": "<string>"
    }
  ],
  "action_signatures": [
    {
      "encoded_message_event_detail": "<string>",
      "message_event_signature": {
        "message_signing_key_info_list": [
          {
            "member_id": "<string>",
            "public_key_version": "<string>",
            "signing_public_key": "<string>"
          }
        ],
        "public_key_version": "<string>",
        "signature": "<string>",
        "signature_version": "<string>",
        "signing_public_key": "<string>"
      },
      "message_id": "<string>",
      "signature_payload": "<string>"
    }
  ],
  "base64_encoded_key_rotation": "<string>"
}
'

200

{
  "data": {
    "sequence_id": "<string>"
  },
  "errors": [
    {
      "title": "<string>",
      "type": "<string>",
      "detail": "<string>",
      "status": 123
    }
  ]
}

Authorizations

OAuth2UserTokenUserToken

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

id · string · required

The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g'). Identifies the conversation target. Accepts three formats: (1) a recipient user ID for 1:1 conversations (e.g., '1215441834412953600'), (2) a legacy 1:1 conversation ID with two user IDs separated by a dash (e.g., '1215441834412953600-1603419180975409153'), or (3) a group conversation ID prefixed with 'g' (e.g., 'g1234567890123456789'). The server constructs the canonical conversation ID from the authenticated user and recipient when a single user ID is provided.

Pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$

Example:

"1215441834412953600"

Body

application/json

conversation_key_version · string · required

Version of the conversation encryption key (typically a timestamp in milliseconds).

conversation_participant_keys · object[] · required

The conversation key encrypted for each participant using their public key.

Show child attributes

action_signatures · object[]

Cryptographic signatures for the key initialization action.

Show child attributes

base64_encoded_key_rotation · string

Base64-encoded key rotation payload for ratchet tree key management.

Response

200

application/json

The request has succeeded.

data · object

Show child attributes

errors · object[]

Minimum array length: 1

An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Show child attributes