Skip to main content

List incoming messages (all channels)

GET 

/api/v1/messages/inbound

Retrieve the replies your HelloSMS account has received on every channel, newest first. Each message has a channel, sms or rcs, so one call returns your SMS and RCS replies together.

If your account doesn't use RCS, everything here is SMS: every message's channel reads sms, and the RCS parts don't apply to you.

This is the all-channel version of List inbound messages, which covers SMS only. It takes the same parameters and pages the same way: up to 1000 messages per page, with page and number. Switching from one to the other means changing the path and reading channel.

A few things differ from the SMS-only endpoint:

  • RCS replies don't arrive on one of your numbers, so setting number leaves them out. Leave number out to get every reply.
  • timestamp is a number here, not a string.
  • RCS replies add fields that tell you what the recipient did: replyType says whether it was a text, a postback (the recipient tapped a reply button), a location or a file. The fields that don't apply to a message are left out.

Each message has toSenderId, the id of your number or RCS sender that the reply reached. It is the id List senders returns for a number, and the id List RCS senders returns for an RCS sender. To reply from the number the customer wrote to, use toSenderId as senderId in Send SMS. To reply from the same RCS sender, use it as rcsSenderId in Send RCS.

Photos and files. A file reply has a media object. While media.state is available, media.url is a link to the file that works for one hour, and media.urlExpiresAt is the time it stops working. Call the endpoint again to get a fresh link. Links are made when you ask, so don't store them. A photo we could not fetch reads unavailable and has no url.

Request​

Query Parameters

    page integer

    Specify the page number of results you want to retrieve. Each page holds up to 1000 messages. If you don´t provide a page number, the API will return the first page by default.

    number string

    Show only the SMS replies received by this number of yours. The value should match the to field of an SMS reply. Setting it leaves out RCS replies, which don´t arrive on a number. A number that isn't on your account returns a 400 with number not found.

Responses​

The list of incoming messages was successfully retrieved.