Get Message by ID API

This API allows you to retrieve metadata about a specific message sent via our API via its id. The most common use case for this API is to check on the status of a message.

How It Works

To use this API, you must save the id field in the response returned when making an API call to send the Gov.sg message.

Get transactional GovSG by ID

GET/v1/transactional/govsg/{messageId}

Authorization

bearerAuth

Path parameters

messageId*string

Response

200400401404500

Successfully retrieved transactional GovSG message with corresponding ID

Body

application/json

idstring

recipientstring

template_idnumber

paramsobject

language_codestring

created_atstring (date-time)

updated_atstring (date-time)

accepted_atstring (date-time)

sent_atstring (date-time)

delivered_atstring (date-time)

read_atstring (date-time)

errored_atstring (date-time)

error_codestring

This error code corresponds with error codes from our service providers:

• WhatsApp

error_descriptionstring

Human-readable details about the message error.

statusenum

• UNSENT - initial state of a newly created transactional GovSG message (this status is not returned in the course of a successful request to send a GovSG message)
• ACCEPTED - Message has been accepted by our service provider (this status is returned in the course of a successful request to send a GovSG message)
• SENT - the send request was successfully forwarded to our service provider and our service provider will attempt to deliver the message to the recipient’s phone number (API user can check this and all subsequent statuses via the /transactional/govSG/{messageId} endpoint)
• DELIVERED - the service provider has successfully delivered the message to the recipient's phone number
• READ - the recipient has received the message and viewed it
• ERROR - an error happened when the service provider is trying to deliver the message

UNSENTACCEPTEDSENTDELIVEREDERROR

Request

JavaScriptCurl

const response = await fetch('/v1/transactional/govsg/{messageId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "id": 42,
  "recipient": "98765432",
  "template_id": 2,
  "language_code": "en_GB",
  "created_at": "2024-04-28T16:51:20.945Z",
  "updated_at": "2024-04-28T16:51:20.945Z",
  "accepted_at": "2024-04-28T16:51:20.945Z",
  "sent_at": "2024-04-28T16:51:20.945Z",
  "delivered_at": "2024-04-28T16:51:20.945Z",
  "read_at": "2024-04-28T16:51:20.945Z",
  "errored_at": "2024-04-28T16:51:20.945Z",
  "error_code": "text",
  "error_description": "text",
  "status": "UNSENT"
}

Example Response

{
  "id": "505",
  "recipient": "[phone]",
  "template_id": "1",
  "params": {
    "topic": "document collection",
    "agency": "Open Government Products",
    "timeslot": "1-3PM",
    "officer_name": "John Tan",
    "recipient_name": "Stanley Nguyen",
    "officer_designation": "Reception Officer"
  },
  "language_code": "en_GB",
  "created_at": "2023-07-31T16:39:59.631Z",
  "updated_at": "2023-07-31T16:40:02.558Z",
  "accepted_at": "2023-07-31T16:40:01.526Z",
  "sent_at": "2023-07-31T16:40:01.000Z",
  "delivered_at": "2023-07-31T16:40:02.000Z",
  "read_at": null,
  "errored_at": null,
  "error_code": null,
  "error_description": null,
  "status": "DELIVERED"
}