Send Message API

Updated 25 October 2023 We have stopped onboarding new agencies to the Gov.sg WhatsApp channel

Overview

This endpoints accept a request body that contains information about the Gov.sg WhatsApp message to be sent. Each successful request to this endpoint will send out a single Gov.sg WhatsApp message.

Send a transactional GovSG message

POST/v1/transactional/govsg/send

Authorization

bearerAuth

Body

application/json

recipient*string

Mobile phone number of the recipient without special formatting (only contains numerical characters and prefixed with plus sign if country code is included).

Notes:

• Country code will need to be provided for non-SG mobile numbers.
• If country code is not provided, the phone number will be defaulted to be an SG number.

template_id*number

language_codestring

params*object

Response

201400401429500

Created. The message is being sent.

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/send', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "recipient": "81234567",
      "template_id": 2,
      "params": {
        "officer_name": "John Tan"
      }
    }),
});
const data = await response.json();

Response

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

Request Body

1. recipient: Mobile phone number of the recipient without special formatting (only contains numerical characters and prefixed with plus sign if country code is included).

   Notes:

   • Country code will need to be provided for non-SG mobile numbers.

   • If country code is not provided, the phone number will be defaulted to be an SG number.

2. template_id: ID of the template that suits your need (can be retrieved from GET templates endpoint)

3. params: A key-value object with keys being the parameter names (wrapped in double curly braces in the template body) and corresponding string values to fill in the template body.

4. language_code (optional): The language code that can be retrieved from the multilingual_support field of the template

API Response

For general information about our API response formats, see here.

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:01.526Z",
  "accepted_at": "2023-07-31T16:40:01.526Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "errored_at": null,
  "error_code": null,
  "error_description": null,
  "status": "ACCEPTED"
}

For message status, we have 6 different states that a message can be in:

• UNSENT - Initial state of a newly created transactional Gov.sg 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 Gov.sg 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