Difference between revisions of "Sending a Direct Message"

Latest revision as of 14:29, 12 May 2016

This topic covers how to send a direct message from one address to another trusted direct address. For additional information regarding what direct messaging is, please review this topic.

Prerequisites

It is required to have an active practice with a valid direct domain, as well as an active user with a valid direct address value associated with their record. The next few sections cover how to set that up.

Set up practice

General instructions can be found here on how to create a practice, but the critical component to specify in the API request when setting up a practice that will want to communicate via direct messages is the directDomain. Submitting a single string value results in that name being prepended to the root direct domain value as a subdomain. For partners utilizing the domain bound certificate type, each account/practice should have their own unique subdomain value. After submitting, the PracticeList API can be called and the full domain is viewable in the response for each account.

Set up user

Instructions outlined here outline the general process for establishing a user. The critical part of this for direct communication is the directAddress value sent in the request. This is the local part of the direct email address and gets prepended to the left of the @.

Identity Verification

At this point, if the previous steps of setting up a practice and user are in place, the user is able to access the self service identity verification user interface. This step is optional if you are in a testing environment as once the practice is saved, a certificate is already created. And once a user is established, a complete direct email address is now configured and able to receive inbound direct messages from trusted sources. Additional information regarding this can be found here. Again, if you are in a testing environment this is not necessary. However, if it is still desired to do so, this can be accomplished by completing the process using one of the testcases provided here.

Identify Direct recipient

The first step to sending a direct message is choosing a recipient. It is encouraged to start by sending to the user's own direct address to verify the message can go round trip. To verify the user's direct address, calling UserList will return a response of each user and what their full direct email address is. Alternatives to the user sending themselves would be a 3rd party address Updox trusts like HealthVault.

Validate Direct Address Recipient

Once a recipient is identified, the next step is checking if there is a trust between the sender and receiver. To verify this use API method DirectAddressValidate which is found on the Interactive API page under the DirectActions section. Inside the response there is validDirectAddress which will be a boolean indicator if it is trusted.

Sending a Direct Message

There are 2 ways to send a direct message:

• DirectSimpleSend

• DirectMessageSend

The difference between these 2 APIs is you can send to multiple recipients with DirectMessageSend, whereas DirectSimpleSend only goes to one recipient. When sending you have the ability to specify html, plain text, as well as include attachments. The attachments should be base64 encoded and contain the file mime type as well as the file name.