Create Scheduled Message

Description

The Schedule Message API allows you to schedule messages for a future send to a Hi Marley case from any system.

Service Name	Scheduled Message
Service Type	REST
Method	POST
UAT (Sandbox) URL	https://integration.uat.marley.ai/api/case/:caseId/scheduled-messages
Production URL	https://integration.himarley.io/api/case/:caseId/scheduled-messages
Technical Documentation	View technical documentation with sample request and response payloads hosted on Postman.

Table of Contents

• API Request
  • Flow
  • Request Payload Example
  • Request Field Breakdown
  • ISO 8601 Formatted Timestamp
• API Response 
  • Response Payload Example
  • Response Fields Breakdown
• Common Errors to Handle
  • Operator Not Found
  • Scheduled Time is in the Past
  • Missing Message Body Parameter
  • [404] Case Not Found

API Request

Flow

1. Send API Request with Hi Marley caseId, scheduledTime, and generated message from your system.
2. Hi Marley receives requests and validate Request Payload elements (see request field breakdown).
3. API Response received with either success or error message based on validation. Success indicates that message will be processed and sent shortly.
4. Hi Marley sends message to customer on the case using the specified operator account.

Request Path Breakdown

Property	Values	Description	Type	Required	Example	Validation
caseId		The Case ID associated with the Hi Marley Case.	string	true	364ef9bb-fae5-4e2a-a746-cdca465a9c16	caseId exists within Hi Marley.

 

Request Payload Example

{
  "message": "Is there anything else we can help with?",
  "scheduledTime":"2022-11-02T14:35:00-04:00",
  "operator": {
    "email":"[e-mail]"
  }
}

 

Request Field Breakdown

Property	Values	Description	Type	Required	Example	Validation
scheduledTime		ISO 8601 formatted timestamp string to indicate the time that the message will be sent.	string	true	"scheduledTime":"2022-11-02T14:35:00-04:00"	Time is not in the past
message		Content of the message that is sent to the case in Hi Marley.	string	true	"messageBody": "Is there anything else we can help with?"	Non-empty string value
source	operator account object	The message will come from a specific operator account.	object	true	"operator":{"email":"[e-mail]"}	Operator email linked to active Hi Marley account

ISO 8601 Formatted Timestamp

The ISO 8601 timestamp allows for different representations of time, date, and timezone to allow for a precise timestamp based on how you want to integrate with your system.

Learn more about this format : W3C ISO 8601 Timestamp Documentation

 

API Response 

Response Payload Example

{
  "id": "05ead4e5-6691-4e60-b939-9ee45f155e16",
  "message": "Is there anything else we can help with?",
  "scheduledTime": "2022-11-02T14:35:00-04:00",
  "operator": {
    "email":"[e-mail]"
  }
}

Response Fields Breakdown

Property	Values	Description	Type	Required	Example
id		Unique identifier for the scheduled message (separate from the id assigned to the message once sent)	UUID	true	"id": "05ead4e5-6691-4e60-b939-9ee45f155e16"
scheduledTime		ISO 8601 formatted timestamp string to indicate the time that the message will be sent.	string	true	"scheduledTime":"2022-11-02T14:35:00-04:00"
message		Content of the message that is sent to the case in Hi Marley.	string	true	"messageBody": "Is there anything else we can help with?"
source	operator account object	The message will come from a specific operator account.	object	true	"operator":{"email":"[e-mail]"}

 

Common Errors to Handle

• [404] Case Not Found - More Details

Operator Not Found

Description

The operator in the requestBody is not linked to an active Hi Marley account.

Possible Resolutions

• Create operator account via API or Webapp and retry API call.
• Resend API Request with a different operator email.

Example

{
  "errors": [
    {
      "code": "ScheduledMessageNotCreated",
      "category": "NotFound",
      "retryable": false,
      "status": 404,
      "detail": "operator [e-mail] not found",
      "path": "/cases/{caseId}/scheduled-messages",
      "method": "POST",
      "requestId": "1b981fef-4fbf-4823-b91f-b3a12800d0ed"
    }
  ]
}

Scheduled Time is in the Past

Description

Time indicated in the scheduledTime requestBody element is in the past. 

Possible Resolutions

• Retry API request with corrected scheduledTime element.

Example

{
  "errors": [
    {
      "code": "ScheduledMessageNotCreated",
      "category": "DataValidationError",
      "retryable": false,
      "status": 400,
      "detail": "scheduledTime 2022-11-28T15:20:00.000Z is in the past",
      "path": "/cases/{caseId}/scheduled-messages",
      "method": "POST",
      "requestId": "a9d883e5-fd90-4c39-a9fb-9c83c10ca979"
    }
  ]
}

 

Missing Message Body Parameter

Description

Element messageBody in API request is missing, contains empty quotations.

Possible Resolutions

• Retry API request with corrected messageBody element.

Example

{
   "errors" : [
      {
         "code" : "SendMessageMissingParams",
         "category" : "DataValidationError",
         "retryable" : false,
         "status" : 400,
         "detail" : "Missing required parameters [\"message\"]",
         "path" : "/case/actions/send-message",
         "method" : "POST",
         "requestId" : "6c4396dd-81b4-4897-8a94-f3191bd80086"
      }
   ]
}