Communication
An occurrence of information being transmitted; e.g. a message that was sent to a responsible provider
https://hl7.org/fhir/R4/communication.html
The Communication resource maps to messages in Canvas between a patient and practitioner. Click here to learn more.
Additional HTML formatting
With the release of Advanced Letter Templates, Messages are now saved in the database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before this update (10/26/2022 @ 17:00 PST) will remain in plain text format.
Communication create
Messages created through this endpoint will be added to the patient’s timeline and in the patient app based on the ingestion date into Canvas.
Attributes
The FHIR Resource name.
The status of the transmission.
While status is a required attribute, all communication messages will be created with a completed status regardless of what is supplied in the payload.
When sent
ISO 8601 format
If not supplied on creation, it will default to the current timestamp.
When received
ISO 8601 format
If no received datetime is supplied when the recipient of the message is a Practitioner, the message will appear on the subject’s timeline as unread, indicated by a blue circle on the message icon. The practitioner will have the ability to mark the communication message as read in the Canvas UI which will update this attribute.
Message recipient.
Supported reference types are a single Patient or Practitioner.
Between the sender and recipient, one must be a practitioner while the other must be a patient. When the sender is a RelatedPerson, the recipient must be a practitioner.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".
Type the reference refers to (e.g. “Patient” or “Practitioner”).
Message sender.
Supported reference types are a single Patient, Practitioner, or RelatedPerson. A RelatedPerson sender is a family member or other representative who sent the message through family portal access. The reference is to the RelatedPerson their access was given from, even when they also have a chart of their own.
Between the sender and recipient, one must be a practitioner while the other must be a patient.
To send a message as a family member, set sender to the RelatedPerson their access was given from and recipient to a practitioner. Canvas files the message on that RelatedPerson’s patient’s chart, sent from the family member’s own portal login.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787", "Practitioner/ed1e304acdb847148338c6b0596d93fd", or "RelatedPerson/3f1b2c7d8e9a4b5c6d7e8f9a0b1c2d3e".
Type the reference refers to (e.g. “Patient”, “Practitioner”, or “RelatedPerson”).
Message payload.
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Message part content.
Responses
Canvas returns the created resource's id as a UUID within the
location header and a null response body.Errors
Communication read
Read a Communication resource.
Path Parameters
Response Payload Attributes
The FHIR Resource name.
The identifier of the communication.
The status of the transmission.
A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as completed. For draft messages in Canvas, they will appear in FHIR as preparation. While a FHIR status of in-progress are Canvas messages that are scheduled to be delivered at a later time.
Focus of the message. Always a Patient reference: the patient whose chart the message is filed on. For a message a family member or other representative sent through family portal access, that’s the chart they sent it on, even when they have a chart of their own.
The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".
Type the reference refers to (e.g. “Patient”).
When sent
ISO 8601 format
When received
ISO 8601 format
Messages sent via Canvas UI to a patient will not have a received timestamp.
If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.
Message recipient.
Supported reference types are a single Patient or Practitioner.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".
Type the reference refers to (e.g. “Patient” or “Practitioner”).
Message sender.
Supported reference types are a single Patient, Practitioner, or RelatedPerson. A RelatedPerson sender is a family member or other representative who sent the message through family portal access. The reference is to the RelatedPerson their access was given from, even when they also have a chart of their own.
When Canvas can no longer name the RelatedPerson a family member’s message came from, sender is the family member’s own Patient reference if they have a chart, and is left out if they don’t.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787", "Practitioner/ed1e304acdb847148338c6b0596d93fd", or "RelatedPerson/3f1b2c7d8e9a4b5c6d7e8f9a0b1c2d3e".
Type the reference refers to (e.g. “Patient”, “Practitioner”, or “RelatedPerson”).
Message payload.
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Message part content.
Responses
Errors
Communication search
Communication search will only return messages between a practitioner and patient, including a family member’s messages to a practitioner, not between two practitioners.
Query Parameters
The unique Canvas identifier of the Communication.
The patient reference that is the subject of the communication in the format Patient/a39cafb9d1b445be95a2e2548e12a787.
Message recipient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".
Message sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787", "Practitioner/ed1e304acdb847148338c6b0596d93fd", or "RelatedPerson/3f1b2c7d8e9a4b5c6d7e8f9a0b1c2d3e". A Patient sender matches the messages that patient sent on their own chart, not ones they sent on another chart through family portal access. A RelatedPerson sender matches the messages family members sent through the access given from that RelatedPerson, including after staff removed the contact from the chart.
Response Payload Attributes
The FHIR Resource name.
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
The number of resources that match the search parameter.
Attributes relevant to pagination, see our Pagination page for more detail.
The relation of the page search
The search url for the specific relation
The results bundle that lists out each object returned in the search
The attributes specific to the resource type, see the Attributes section below
Attributes
The FHIR Resource name.
The identifier of the communication.
The status of the transmission.
A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as completed. For draft messages in Canvas, they will appear in FHIR as preparation. While a FHIR status of in-progress are Canvas messages that are scheduled to be delivered at a later time.
Focus of the message. Always a Patient reference: the patient whose chart the message is filed on. For a message a family member or other representative sent through family portal access, that’s the chart they sent it on, even when they have a chart of their own.
The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".
Type the reference refers to (e.g. “Patient”).
When sent
ISO 8601 format
When received
ISO 8601 format
Messages sent via Canvas UI to a patient will not have a received timestamp.
If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.
Message recipient.
Supported reference types are a single Patient or Practitioner.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".
Type the reference refers to (e.g. “Patient” or “Practitioner”).
Message sender.
Supported reference types are a single Patient, Practitioner, or RelatedPerson. A RelatedPerson sender is a family member or other representative who sent the message through family portal access. The reference is to the RelatedPerson their access was given from, even when they also have a chart of their own.
When Canvas can no longer name the RelatedPerson a family member’s message came from, sender is the family member’s own Patient reference if they have a chart, and is left out if they don’t.
The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787", "Practitioner/ed1e304acdb847148338c6b0596d93fd", or "RelatedPerson/3f1b2c7d8e9a4b5c6d7e8f9a0b1c2d3e".
Type the reference refers to (e.g. “Patient”, “Practitioner”, or “RelatedPerson”).
Message payload.
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Message part content.
Responses
Errors
curl --request POST \ --url 'https://fumage-example.canvasmedical.com/Communication' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "resourceType": "Communication", "status": "unknown", "sent": "2022-04-29T13:30:00.000Z", "received": "2022-04-29T13:30:00.000Z", "recipient": [ { "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd" } ], "sender": { "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14" }, "payload": [ { "contentString": "Upcoming appointment" } ] }'import requests url = "https://fumage-example.canvasmedical.com/Communication" payload = { "resourceType": "Communication", "sent": "2022-04-29T13:30:00.000Z", "received": "2022-04-29T13:30:00.000Z", "recipient": [{ "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd" }], "sender": { "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14" }, "payload": [{ "contentString": "Upcoming appointment" }] } headers = { "accept": "application/json", "Authorization": "Bearer <token>", "content-type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text)
null{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "details": { "text": "Bad request" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "not-supported", "details": { "text": "Operation is not supported" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "business-rule", "details": { "text": "Unprocessable entity" } } ] }
curl --request GET \ --url 'https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json'import requests url = "https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd" headers = { "accept": "application/json", "Authorization": "Bearer <token>" } response = requests.get(url, headers=headers) print(response.text)
{ "resourceType": "Bundle", "type": "searchset", "total": 1, "link": [ { "relation": "self", "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0" }, { "relation": "first", "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0" }, { "relation": "last", "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0" } ], "entry": [ { "resource": { "resourceType": "Communication", "id": "7433b4b2-0d18-45ca-bb12-71105c80386b", "status": "completed", "sent": "2021-03-21T10:46:17+00:00", "received": "2022-03-14T12:03:58.958000+00:00", "subject": { "reference": "Patient/4c21512185184e579b09bfac16dfdd2f", "type": "Patient" }, "recipient": [ { "reference": "Patient/4c21512185184e579b09bfac16dfdd2f", "type": "Patient" } ], "sender": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e", "type": "Practitioner" }, "payload": [ { "contentString": "Similique amet at est necessitatibus repellendus eius." } ] } } ] }{ "resourceType": "OperationOutcome", "id": "101", "issue": [ { "severity": "error", "code": "invalid", "details": { "text": "Bad request" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }
curl --request GET \ --url 'https://fumage-example.canvasmedical.com/Communication/<id>' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json'import requests url = "https://fumage-example.canvasmedical.com/Communication/<id>" headers = { "accept": "application/json", "Authorization": "Bearer <token>" } response = requests.get(url, headers=headers) print(response.text)
{ "resourceType": "Communication", "id": "17b7d61e-4b0e-4940-bd37-b64f5c2ae29d", "status": "completed", "sent": "2023-10-23T21:19:22.865089+00:00", "received": "2023-10-23T21:21:00.000000+00:00", "subject": { "reference": "Patient/43f1418bae9c41919203e0006761067c", "type": "Patient" }, "recipient": [ { "reference": "Practitioner/3640cd20de8a470aa570a852859ac87e", "type": "Practitioner" } ], "sender": { "reference": "Patient/43f1418bae9c41919203e0006761067c", "type": "Patient" }, "payload": [ { "contentString": "What's up doc?" } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }