Holder messaging via DIDComm

Holder messaging enables secure, encrypted communication between organizations and digital wallet holders using the DIDComm protocol. This feature allows verifiers to send authenticated requests directly to credential holders' wallets, enabling real-time verification workflows without requiring traditional authentication methods.

Example use case

Consider a customer service scenario where enhanced identity verification is needed. A customer calls their bank to request a credit limit increase or password change. Rather than relying solely on traditional phone-based verification, the call center can leverage the customer's existing digital credentials for stronger authentication.

The process works as follows: the customer receives a credential during onboarding. The call center agent can initiate a credential verification request. The customer receives a secure message in their digital wallet via push notification, reviews the request, and responds using biometric authentication to unlock their wallet and confirm the data sharing.

Technical implementation

Prerequisites

Issuer has captured the holder's DID
Issuer is using a valid message schema

Current Truvera wallet implementation supports only YES/NO holder messaging schema. Customers using the wallet SDK can implement custom schemas based on their needs.

Encrypted message dispatch

Uses the Truvera API to send an encrypted DIDComm message to the holders DID.

On steps how to create the sender DID see the Create DID or step by step instructions in the Truvera Workspace.\

Static key (did:key method) cannot be used for the senders DID. Please use other available methods (e.g. did:cheqd). Recipient DID from the holder wallet will be a did:key.

The message script:

const axios = require("axios").default;
const API_KEY = ;//Your Truvera API key// 
const API_URL = "https://api-testnet.truvera.io";//for production https://api.truvera.io
const WALLET_DID = ;//Holders wallet DID//

const apiClient = axios.create({
  baseURL: API_URL,
  headers: {
    "Content-Type": "application/json",
    "User-Agent": "insomnia/9.3.2",
    Authorization: `Bearer ${API_KEY}`,
  },
});

async function sendYesNoMessage() {
  const payload = {
    type: "text",
    payload: {
      senderName: , //Name of the message sender DID//
      senderDid: , //Message sender DID//
      senderLogo: , //Logo of the message sender DID//
      title: "Are you currently speaking with our customer support team?",
      question:
        "This confirms you initiated the call and helps prevent fraud. Your personal information will not be shared.",
      yesText: "Yes",
      noText: "No",
      expirationDate: new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString(),
      messageId: 'Internal-message-1234'//add a message ID to track the message
    },
    type: "https://schema.truvera.io/yes-no-payload-V1.json",
    senderDid: ,//the message sender DID//
    algorithm: "ECDH-1PU+A256KW",
    recipientDids: [WALLET_DID],
  };

  const { data: encryptedMessage } = await apiClient.post(
    "/messaging/encrypt",
    payload
  );
  console.log("Message encrypted successfully:", encryptedMessage);

  const sendPayload = {
    to: WALLET_DID,
    message: encryptedMessage.jwe,
  };

  const { data: sentMessage } = await apiClient.post(
    "/messaging/send",
    sendPayload
  );
  console.log("Message sent successfully:", sentMessage);
}


sendYesNoMessage();

Response payload from the wallet

{
    "messageId": "f07b97220782dd2c66df0180f09ad4cdd8d8671b2a86218129e4c721c03dfa5e",
    "to": "did:cheqd:testnet:senderDID",
    "messageType": "https://schema.truvera.io/yes-no-response-V1.json",
    "sender": null,
    "receivedAt": "2025-09-04T12:25:29.331Z",
    "content": {
        "id": "3d287880-898a-11f0-8698-4d8b1173feb3",
        "type": "https://schema.truvera.io/yes-no-response-V1.json",
        "created_time": 1756988727,
        "from": "did:key:holderDID",
        "body": {
            "messageId": "internal-message-1234",
            "response": "no"
        },
        "to": [
            "did:cheqd:testnet:senderDID"
        ]
    }
}

Response notification and retrieval

Configure a webhook via the API or the Truvera Workspace to listen to didcomm_message_received event.

You can also get all the received messages using the API.

List DIDComm messages

get

/messaging/messages

Retrieve a list of DIDComm messages for the authenticated user. Messages are returned in reverse chronological order (newest first).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

offsetinteger · int32Optional

How many items to offset by for pagination

Default: 0

limitinteger · int32 · min: 1 · max: 64Optional

How many items to return at one time (max 64)

Default: 64

tostring · min: 32Optional

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

messageTypestringOptional

Filter messages by type (e.g., 'https://didcomm.org/basicmessage/2.0/basic-message')

Responses

200

A paged array of DIDComm messages

application/json

totalintegerOptional

Total number of messages available

Example: 150

offsetintegerOptional

Current offset for pagination

Example: 0

limitintegerOptional

Current limit for pagination

Example: 64

400

Invalid request parameters

application/json

401

Authentication required

application/json

get

/messaging/messages

GET /messaging/messages HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "messages": [
    {
      "messageId": "msg_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "to": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "messageType": "https://didcomm.org/basicmessage/2.0/basic-message",
      "sender": "did:example:sender",
      "receivedAt": "2024-01-15T10:30:01Z",
      "content": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "total": 150,
  "offset": 0,
  "limit": 64
}

To get the message content make an API call to retrieve the full response.

Get a specific DIDComm message

get

/messaging/messages/{messageId}

Retrieve a specific DIDComm message by its ID. Only messages owned by the authenticated user can be retrieved.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

messageIdstringRequired

The unique identifier of the message

Example: msg_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdefPattern: ^[a-f0-9]{64}$

Responses

200

The requested DIDComm message

application/json

A DIDComm message with metadata

messageIdstringRequired

Unique identifier for the message

Example: msg_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

tostringRequired

The DID that received this message

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

messageTypestringOptional

The type of the message (from the message content)

Example: https://didcomm.org/basicmessage/2.0/basic-message

senderstring · nullableOptional

The DID of the message sender (if available)

Example: did:example:sender

receivedAtstring · date-timeRequired

When the message was received

Example: 2024-01-15T10:30:01Z

400

Invalid message ID format

application/json

401

Authentication required

application/json

404

Message not found or not owned by user

application/json

get

/messaging/messages/{messageId}

GET /messaging/messages/{messageId} HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "messageId": "msg_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "to": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
  "messageType": "https://didcomm.org/basicmessage/2.0/basic-message",
  "sender": "did:example:sender",
  "receivedAt": "2024-01-15T10:30:01Z",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

PreviousTeams NextMessaging API calls

Last updated 5 months ago

Was this helpful?

hashtagExample use case

hashtagTechnical implementation

hashtagPrerequisites

hashtagEncrypted message dispatch

hashtagResponse payload from the wallet

hashtagResponse notification and retrieval

hashtagList DIDComm messages

hashtagGet a specific DIDComm message

Example use case

Technical implementation

Prerequisites

Encrypted message dispatch

Response payload from the wallet

Response notification and retrieval

List DIDComm messages

Get a specific DIDComm message