Message

Message is a resource that represents a message that has been sent or received in a conversation with a candidate. A message is always associated with a MessageThread.

On WhatsApp a message can only be sent within the 24 hour window after the latest message from the candidate. If used outside of this window, the message will not be sent. This restriction does not apply to other channels.

Endpoints

• GET /messages - Retrieves a list of all messages.

• GET /messages/{id} - Retrieves a specific message by ID.

• POST /messages - Send and create a new message.

• PATCH /messages/{id} - Updates a specific message by ID.

• DELETE /messages/{id} - Deletes a specific message by ID.

Attributes

Field	Type	Description	Writable
id	UUID	Unique identifier for the message.	true
sendBy	String	Sender of the message.	true
origin	String	Specifies the origin of the message.	true
messageThreadId	UUID	Identifier of the associated Message thread.	true
payload	JSON Object	Data content of the message, can be 'text' or 'template'.	true
deliveryStatus	String	Status of the message delivery.	true
errorMessages	Array	Error messages if any occurred during handling.	true
createdAt	DateTime	The timestamp when the message was created.
updatedAt	DateTime	The timestamp when the message was last updated.

HTTP Methods

Field	GET	POST	PATCH
id	X
sendBy	X	X	X
origin	X
messageThreadId	X	X
payload	X	X	X
deliveryStatus	X
errorMessages	X
createdAt	X
updatedAt	X

Required Fields for Creation (POST)

Field	Type	Example value
sendBy	String	"Recrubo"
messageThreadId	UUID	"7f9a9715-5e7c-4328-ab47-bb9e595438c9"
payload	JSON Object	{ "type": "text", "attributes": { "value":"Hey! Lets start the chat" } }

Payload values

We currently support the following types of messages:

Text

A simple text message that can be sent to the candidate. The text message can contain a single text component. A text message consists of the following attributes: text.

example of a text message:

{
  "type": "text",
    "text": {
      "value": "Hello, how are you doing today?"
    }
}

Media

A message with media attached can be sent to a candidate. The message can contain media such as an image, video, audio or document. The media message consists of the following attributes: type, send_by and an image object containing caption, filename, data, and mime_type.

It's essential to note that when sending a message with media, the value you give for the "type" attribute must correspond with the key used for the media object.

Example of a media message:

{
    "type": "image",
    "image": {
        "caption": "A caption",
        "filename": "A file name",
        "data": "8J+Yig==", // base64 encoded string
        "mime_type": "image/jpeg"
    }
}

Template

A templated message can contain variables in the header and footer component. A template consists of the following attributes: id and components. The id is the id of the MessageTemplate to be sent. The components attribute is an array of objects representing the variable values inserted into the template per component. These can be in the header or body of the template.

The variables are inserted in order of the array so if the body of the template has 2 variables the first variable in the array will be inserted in the first variable placeholder {{1}} and the second variable in the second variable placeholder {{2}}.

Example of a template without variables:

{
    "type": "template",
    "template": {
        "id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
        "components": []
    }
}

example of a template with variables:

 {
  "type": "template",
  "template": {
    "id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "text": "Recrubo",
            "type": "text"
          }
        ]
      }
    ]
  }
}

Delivery Status

• accepted - The message has been accepted by the platform and is being processed.

• sent - The message has been sent to the candidate.

• delivered - The message has been delivered to the candidate.

• read - The message has been read by the candidate.

• failed - The message has failed to be delivered to the candidate.

Note: The delivered and read status are only available if the channel supports these statuses.

POST Message example

{
    "data": {
        "type": "messages",
        "attributes": {
            "messageThreadId": "f45e385c-3a82-4360-9361-ec78769fdda0",
            "payload": {
                "type": "template",
                "send_by": "Recrubo",
                "template": {
                    "id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
                    "components": [
                        {
                            "type": "body",
                            "parameters": [
                                {
                                    "text": "Recrubo",
                                    "type": "text"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Example response

{
    "data": {
        "id": "ad643dcb-8a95-4d86-84b2-cf1c00a86157",
        "type": "messages",
        "attributes": {
            "createdAt": "2024-05-06T11:49:07+00:00",
            "updatedAt": "2024-05-06T11:49:07+00:00",
            "sendBy": null,
            "origin": "outbound",
            "messageThreadId": "f45e385c-3a82-4360-9361-ec78769fdda0",
            "payload": {
                "type": "template",
                "template": {
                    "name": "recruitee_new_candidate",
                    "preview": "Hallo {{1}} Wat leuk dat je bij ons wil komen werken! Antwoord op dit bericht om je afsrpaak in te plannen.",
                    "language": "nl",
                    "components": [
                        {
                            "type": "header",
                            "parameters": []
                        },
                        {
                            "type": "body",
                            "parameters": [
                                {
                                    "text": "cedric",
                                    "type": "text"
                                }
                            ]
                        }
                    ]
                }
            },
            "deliveryStatus": "accepted",
            "errorMessages": []
        },
        "relationships": {
            "messageThread": {
                "links": {
                    "related": "/public/v2/message-threads/f45e385c-3a82-4360-9361-ec78769fdda0"
                }
            }
        }
    },
    "meta": {}
} 

OpenAPI