Sending messages

In this guide, we will show you how to send messages to your candidates using the Recrubo API.

We currently only support sending text messages to candidates. Support for images, videos, and other media types will soon be added.

Prerequisites

• A MessageThread

• If you are using WhatsApp, you will need to be sure that the 24-hour Conversation window has not expired since the last message was sent by the candidate. If the 24-hour window has expired, you will need to use a MessageTemplate to send a message.

• Webhooks on messages to receive the message status.

Sending a message

To send a message to a candidate, you will need to make a POST request to the public/v2/messages endpoint. The body of the request should include the following fields:

Text message

{
  "data": {
    "type": "messages",
    "attributes": {
      "sendBy": "John",
      "payload": {
        "type": "text",
        "text": {
          "value": "Hi, how are you!"
        }
      }
    },
    "relationships": {
      "messageThread": {
        "data": {
          "type": "messageThreads",
          "id": "f45e395c-3a82-4360-9361-ec78769fdda0"
        }
      }
    }
  }
}

Template message

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

You are also allowed to include the messageThreadId in the attributes of the message to avoid the need to include the relationship.

Response

You will receive a response with the message details, including the message ID, the message text, and the message status.

{
  "data": {
    "id": "972f5cf2-8879-4746-94de-a17e75265373",
    "type": "messages",
    "attributes": {
      "createdAt": "2024-05-07T14:20:46+00:00",
      "updatedAt": "2024-05-07T14:20:46+00:00",
      "sendBy": "John",
      "origin": "outbound",
      "messageThreadId": "f46f385c-3a82-4360-9361-ec78769fdda0",
      "payload": {
        "text": {
          "value": "Hi, how are you!"
        },
        "type": "text"
      },
      "deliveryStatus": "accepted",
      "errorMessages": []
    }
  }
}

Message status will always be accepted if the message was accepted by the external provider. If the message was not accepted, you will receive an error message in the errorMessages field.

accepted does not mean sent. In the case of WhatsApp, if you send a valid message outside the 24 hour window, the message will be accepted but when WhatsApp tries to send it, it will fail. If subscribed to the deliveryStatus field on the Message resource through Webhooks we will notify you by sending a WebhookPayload.

Communication visualized

Fetching messages

You can fetch messages using the message resource. You can filter messages by messageThreadId.

GET /messages?filter[messageThreadId]=f67e385c-3a82-4360-9361-ec78769fdda0

Alternatively, you can fetch messages by message thread using the messageThread resource

GET /message-threads/f67e385c-3a82-4360-9361-ec78769fdda0?include=messages