Send Template Message

POST /api/case/actions/send-template-message/{templateId}

The Send Template Message API allows you to send messages that have a template managed within the Hi Marley web app.

• API call to execute a template message send to an open case.
• Message Templates need to be added by an organizations Admin in the Hi Marley Webapp Manage Tab.

Service Name	Send Template Message
Service Type	REST
Method	POST
Concept	Message Actions
UAT (Sandbox) URL	https://integration.uat.marley.ai/api/case/actions/send-template-message/:templateId
Production URL	https://integration.himarley.io/api/case/actions/send-template-message/:templateId
Technical Documentation	View technical documentation with sample request and response payloads hosted on Postman.

Table of Contents

• Common Errors to Handle
  • Primary Contact not found
  • Failed to retrieve template.
  • Failed to bind template values.

Webapp Configuration - Template Message Set Up

Within the Hi Marley web app, admin users need to navigate to Add New Template + in the Settings Tab. This tab is available to Admins by navigating to Settings > Operational >  Message Templates > New Template.

The API will verify the templateId (name) passed in the request exists within Hi Marley and if it exists will pull the body of the message template.  It is important to note that message template used within the web app functions different if used in the API.  If used within the web app, the variables defined in the message template will be populated with values from Hi Marley.  If the message template is used in the sendTemplateMessage API then the variables will be populated with values from the system sending the message, therefor variables within the message template are not limited to the 'available tokens' referenced in Message Templates guide.

API Flow - Send Template Message 

1. An organizational point person with admin privileges in Hi Marley creates a 'Message Template' under the 'Manage' tab within the Hi Marley web app.  Once the Message Template has been created and saved it is ready for use via the SendMessageTemplate API.
2. SendMessageTemplate API request is made using the required and any optional fields. 
3. Hi Marley API responds with either success indicating that the message will be generated within seconds or an error indicating whether any information is missing from the request or in the webapp (view common errors below).

API Request Fields

Path Elements	Value Options	Description	Type	Required	Example	Validation
templateId		The name of the template message you are sending.	string	true	IA_STAPAssignment	Message template exists within the Hi Marley webapp

Elements	Value Options	Description	Type	Required	Example	Validation
templateValues		Array of variables with values as defined within the message template.	string	true	"claimantFirstName": "Jean-Luc Picard"	Values passed for defined ($)variables in the message template managed within Hi Marley
caseId		The case identifier for the Hi Marley Case.	string	true	"caseId": "c808ba82-e2cb-4a92-9344-b924d79d2308"	CaseID Exists Customer is opted in
source	"ai"	If source is defined as 'ai' the message will come from Marley.	string	false	"source": "ai"	Non-empty string value
	"assigned"	If source is defined as 'assigned' the message will come from the Operator assigned to the Hi Marley case.	string	false	"source": "assigned"	Non-empty string value
	operator email	If email is defined as the source, pass through a email of a user with the role of Operator within Hi Marley.	object	false	"source": { "email":"[e-mail]" }	Operator email linked to active Hi Marley account

 

Building the API Request Example 

Each variable is a key/value pair in the templateValues object.  The key is the name of the variable, and the value is the text to use in place of the variable within the message.

Note: $adjusterName is listed once as a templateValue within the body of the API request.  TemplateValues are sent with actual values from the system sending the API request as opposed to ( $ variables) in the web app. 

{
  "caseId": "c808ba82-e2cb-4a92-9344-b924d79d2308",
  "templateValues": {
    "claimantFirstName": "Jean-Luc Picard",
    "adjusterName": "Marley",
    "adjusterPhoneNumber": "8472203434"
  },
  "referenceId": "Auto-Test272727",
  "source": {
    "email": "[e-mail]"
}
}

API Response Breakdown & Example

Below are examples of a sendTemplateMessage API from a sending system, & the corresponding message displayed in the Hi Marley Webapp.

Message with source = email: [e-mail]

Message with source = assigned

Message with source = ai

API Body response

{
"isAI": false,
"isEvent": false,
"isInbound": false,
"redactionData": [],
"redactionViewedEvents": [],
"isFile": false,
"isImage": false,
"isNote": false,
"isArchived": false,
"isActive": true,
"messageGroup": 0,
"_id": "2d57a656-a8a8-4e5d-9213-9bafc03e09f1",
"chatId": "02462dc8-afb8-4715-8d1e-3ce77189870f",
"authorId": "e16b18d4-d0c7-4e80-8db5-2fcf878d2f25",
"body": "You have the right to have your vehicle repaired at the body shop of your choice. If you'd like us to help you find a shop near you, click HERE.",
"redactedBody": "You have the right to have your vehicle repaired at the body shop of your choice. If you'd like us to help you find a shop near you, click HERE.",
"deliveryStatus": "internalProcessing",
"parentJobId": "",
"organization": "0d24732c-3646-45c5-a313-e3667fb8e6ca",
"creationSource": "PublicApi",
"createdAt": "2022-09-01T17:03:18.706Z",
"updatedAt": "2022-09-01T17:03:18.706Z",
"__v": 0,
"author": {
"languagePreference": "en"
 }
}

Element	Description	Data type	Example
isAI	Was the sent message from source: ai?	boolean	true
isEvent	Is the message a Hi Marley Event?	boolean	false
isInbound	Is the Message Inbound or Outbound.	boolean	false
redactionData		string
redactionViewedEvents
isFile		boolean	false
isImage		boolean	false
isNote		boolean	false
isArchived		boolean	false
isActive		boolean	true
messageGroup		int	0
_id		string	31a731b4-2c17-412f-9352-2dd7d9e04017
chatId		string	47ac964c-1e81-4ed3-b106-f91bd41626d0
body	The body of the message that has been sent.	string	Entire message body...
redactedBody		string
deliveryStatus		string	internalProcessing
parentJobId		string
organization	The Org ID for the associated message.	string	1d2f4e68-d733-477f-acc4-c1c187f0c159
creationSource		string	PublicAPI
createdAt		dateTime	2022-08-26T17:40:41.581Z
updatedAt		dateTime	2022-08-26T17:40:41.581Z
__v		int	0
author
author.languagePreference	The preferred language for the associated message.	string	en

Common Errors to Handle

Primary Contact not found

Description

The operator does not have a valid account in Hi Marley. 

Possible Resolutions

• Add operator account to Hi Marley via the Manage tab (admin role)

Example 

{
    "errors": [
        {
            "code": "UserNotFound",
            "category": "NotFound",
            "retryable": false,
            "status": 404,
            "detail": "User for {\"email\":\"[e-mail]\",\"role\":\"operator\"} not found",
            "path": "/case/actions/send-template-message/{template}",
            "method": "POST",
            "requestId": UUID-String
        }
    ]
}

 

Failed to retrieve template.

Description

The template cannot be found in the Hi Marley org.

Possible Resolutions

• Create template with correct template name in Hi Marley.
• Modify templateId in API request.

Example 

{
    "errors": [
        {
            "code": "SendTemplateMessageIssue",
            "category": "NotFound",
            "retryable": false,
            "status": 404,
            "detail": "Failed to retrieve template.",
            "path": "/case/actions/send-template-message/{template}",
            "method": "POST",
            "requestId": String-UUID
        }
    ]
}

 

Failed to bind template values.

Description

One or more variables used in the template are missing in the API request body.

Possible Resolutions

• Modify the template to use corrected template variables/values.
• Modify the API request to include template variables/values.

Example 

{
    "errors": [
        {
            "code": "SendTemplateMessageIssue",
            "category": "DataValidationError",
            "retryable": false,
            "status": 400,
            "detail": "Failed to bind the following template values\n[\"$message\"]",
            "path": "/case/actions/send-template-message/{template}",
            "method": "POST",
            "requestId": String-UUID
        }
    ]
}