|
| 1 | +# Holder messaging via DIDComm |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +### Example use case  |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +### Technical implementation |
| 12 | + |
| 13 | +#### Prerequisites |
| 14 | + |
| 15 | +* Issuer has captured the holder's DID during credential issuance |
| 16 | + |
| 17 | +#### **Encrypted message dispatch** |
| 18 | + |
| 19 | +Uses the Truvera API to send an encrypted DIDComm message to the holders DID. The message script: |
| 20 | + |
| 21 | +```javascript |
| 22 | +const axios = require("axios").default; |
| 23 | +const API_KEY = ;//Your Truvera API key// |
| 24 | +const API_URL = "https://api-testnet.truvera.io";//for production https://api.truvera.io |
| 25 | +const WALLET_DID = ;//Holders wallet DID// |
| 26 | + |
| 27 | +const apiClient = axios.create({ |
| 28 | + baseURL: API_URL, |
| 29 | + headers: { |
| 30 | + "Content-Type": "application/json", |
| 31 | + "User-Agent": "insomnia/9.3.2", |
| 32 | + Authorization: `Bearer ${API_KEY}`, |
| 33 | + }, |
| 34 | +}); |
| 35 | + |
| 36 | +async function sendYesNoMessage() { |
| 37 | + const payload = { |
| 38 | + type: "text", |
| 39 | + payload: { |
| 40 | + senderName: , //Name of the message sender DID// |
| 41 | + senderDid: , //Message sender DID// |
| 42 | + senderLogo: , //Logo of the message sender DID// |
| 43 | + title: "Are you currently speaking with our customer support team?", |
| 44 | + question: |
| 45 | + "This confirms you initiated the call and helps prevent fraud. Your personal information will not be shared.", |
| 46 | + yesText: "Yes", |
| 47 | + noText: "No", |
| 48 | + expirationDate: new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString(), |
| 49 | + messageId: 'Internal-message-1234'//add a message ID to track the message |
| 50 | + }, |
| 51 | + type: "https://schema.truvera.io/yes-no-payload-V1.json", |
| 52 | + senderDid: ,//the message sender DID// |
| 53 | + algorithm: "ECDH-1PU+A256KW", |
| 54 | + recipientDids: [WALLET_DID], |
| 55 | + }; |
| 56 | + |
| 57 | + const { data: encryptedMessage } = await apiClient.post( |
| 58 | + "/messaging/encrypt", |
| 59 | + payload |
| 60 | + ); |
| 61 | + console.log("Message encrypted successfully:", encryptedMessage); |
| 62 | + |
| 63 | + const sendPayload = { |
| 64 | + to: WALLET_DID, |
| 65 | + message: encryptedMessage.jwe, |
| 66 | + }; |
| 67 | + |
| 68 | + const { data: sentMessage } = await apiClient.post( |
| 69 | + "/messaging/send", |
| 70 | + sendPayload |
| 71 | + ); |
| 72 | + console.log("Message sent successfully:", sentMessage); |
| 73 | +} |
| 74 | + |
| 75 | + |
| 76 | +sendYesNoMessage(); |
| 77 | +``` |
| 78 | + |
| 79 | +#### **Response notification and retrieval** |
| 80 | + |
| 81 | +Configure a webhook via the [API](../webhooks/) or the Truvera [Workspace](../../workspace/creating-api-keys-and-webhook-endpoints.md#h_fae99467a4) to listen to didcomm\_message\_received event.  |
| 82 | + |
| 83 | +You can also get all the received messages using the API. |
| 84 | + |
| 85 | +{% openapi-operation spec="dock-labs-api" path="/messaging/messages" method="get" %} |
| 86 | +[OpenAPI dock-labs-api](https://swagger-api.truvera.io/openapi.yaml) |
| 87 | +{% endopenapi-operation %} |
| 88 | + |
| 89 | +To get the message content make an API call to retrieve the full response. |
| 90 | + |
| 91 | +{% openapi-operation spec="dock-labs-api" path="/messaging/messages/{messageId}" method="get" %} |
| 92 | +[OpenAPI dock-labs-api](https://swagger-api.truvera.io/openapi.yaml) |
| 93 | +{% endopenapi-operation %} |
0 commit comments