List WhatsApp messages

GET

/v1/whatsapp/messages

for await (const msg of bird.whatsapp.list({ status: ["delivered"] })) {
  console.log(msg.id, msg.status);
}

for msg in client.whatsapp.list(status=["delivered"]):
    print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{PhoneNumber: "+15551234567"}) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(msg.Id)
	}
}

foreach ($bird->whatsapp->list(['status' => ['delivered']]) as $message) {
    echo $message->getId(), ' ', $message->getStatus(), "\n";
}

bird whatsapp list

curl -X GET "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Réponse200

{
  "data": [
    {
      "id": "wam_01kya1b3xdq7fe8m2v5t9rncgs",
      "direction": "inbound",
      "from": {
        "phone_number": "+15550002222",
        "bsuid": "US.AbC1",
        "display_name": "Dana Reyes"
      },
      "to": {
        "phone_number": "+15550001111",
        "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg"
      },
      "text": {
        "body": "Got it, thanks."
      },
      "status": "received",
      "created_at": "2026-09-15T14:05:41Z"
    },
    {
      "id": "wam_01kya19eknftrs2s6p82asmvnh",
      "direction": "outbound",
      "from": {
        "phone_number": "+15550001111"
      },
      "to": {
        "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg"
      },
      "text": {
        "body": "The route sheet for Tuesday is up."
      },
      "status": "delivered",
      "recipient_count": 2,
      "delivered_count": 2,
      "read_count": 1,
      "created_at": "2026-09-15T14:03:10Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9"
}

Returns the workspace's WhatsApp messages as a cursor-paginated list, newest first, outbound and inbound alike. Each message carries the one content object it was built from: template, or free-form text, image, video, audio, sticker, document, location, interactive or contact_cards. An inbound message carries interactive_reply when the contact tapped a reply button or a list row, on an interactive message or on a template's quick reply. An inbound message whose content WhatsApp models and we do not carries unsupported instead, naming the type rather than reading back empty. Filter by direction, status, recipient (to), sender (from), business-scoped user ID (bsuid), group (group_id), template category, tag, or creation time. to and from name the same ends of the message the response does, and each accepts an E.164 phone number or a business-scoped user ID. Pair either with direction to search a single side of the message. Neither matches a group, so group_id is what narrows the list to one group's messages. Pass the response's next_cursor back as starting_after to fetch the next page. To follow a single message's delivery, use Get a WhatsApp message instead.

Messages are retained for 30 days. A created_after earlier than that is accepted and raised to the retention bound rather than rejected, so a wider window returns what is still retained instead of failing. There is no way to read messages older than the window.

Paramètres de requête

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

created_afterstring

Limits the response to resources created at or after this timestamp. Combine it with created_before to select a time window. Use an RFC 3339 timestamp with a timezone offset.

created_beforestring

Limits the response to resources created before this timestamp. Combine it with created_after to select a time window. Use an RFC 3339 timestamp with a timezone offset.

statusarray

Filter by status. Repeat the parameter to match any of several statuses.

directionstring

Filter by whether the business sent the message (outbound) or received it from the contact (inbound).

Possible values: outbound, inbound

tostring

Filter by recipient, exact match. The recipient is the contact on an outbound message and your business number on an inbound one, matching the to each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so to=<business-scoped user ID> matches outbound messages only.

fromstring

Filter by sender, exact match. The sender is your business number on an outbound message and the contact on an inbound one, matching the from each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so from=<business-scoped user ID> matches inbound messages only.

phone_numberstring

Deprecated: use to or from instead, which also match a business-scoped user ID. Filters by contact phone number (E.164 exact match), in either direction.

bsuidstring

Filter by business-scoped user ID (Meta identifier), matching the contact in either direction. to and from also accept one, but each matches a single end of the message.

categorystring

Filter by category.

Possible values (may grow over time): authentication, utility, marketing

group_idstring

Filter by the WhatsApp group the message belongs to, in either direction: the group an outbound message was addressed to, or the group an inbound message arrived through. Matches the group_id on each message's to. It names one group, so there is no way to ask for the messages that belong to no group: omit it to list group and one-to-one messages together.

tagarray

Filter by tag. Accepts name to match any record carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A record must match every tag listed to be returned.

Contenu de la réponse

data

array of object

obligatoire

Page of WhatsApp messages, newest first.

Afficher les attributs enfants

data.id

string

obligatoire

ID of the message, assigned when the send is accepted. Pass it as message_id to the get-message and list-events endpoints.

data.direction

string

obligatoire

Whether the message was sent by the business (outbound) or received from the contact (inbound).

Possible values: outbound, inbound

data.from

object

obligatoire

Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.

List WhatsApp messages

Paramètres de requête

Contenu de la réponse

Ressources associées