Sinch Api Messages List

---
name: sinch-api-messages-list
description: List or retrieve messages from Sinch Conversation API
---

# List Messages

List or retrieve messages for a conversation or contact using the Sinch Conversation API. Supports filtering by channel, contact, conversation, and pagination.

**IMPORTANT: Execute this command directly. Do NOT generate script files. Perform the API call immediately.**

## Input

- `--channel` / `-c`: Channel filter (SMS, RCS, WHATSAPP) - optional
- `--contact-id` / `-C`: Contact ID to list messages for - optional
- `--conversation-id` / `-i`: Conversation ID - optional
- `--page-size` / `-n`: Number of results (default 20) - optional
- `--page-token` / `-p`: Pagination token from previous response - optional
- `--format` / `-f`: Output format (table or json) - optional, default table

Arguments: $ARGUMENTS

## Instructions

**Execute these steps directly - do not write code or scripts:**

0. If $ARGUMENTS empty: ask if user wants to list by contact, conversation, or channel; ask for IDs if needed. Otherwise parse.

1. Validate: optional --channel, --contact-id, --conversation-id, --page-size (number), --page-token, --format (table|json).

2. Try MCP tool for listing messages if available (e.g. list-messages). On success format and display result, then exit.

3. If MCP not available: get CONVERSATION_* env vars. If missing, report "Sinch API is not configured."

4. Use Conversation API list messages endpoint(s): e.g. GET /v1/projects/{projectId}/messages or equivalent with query params (contact_id, conversation_id, channel, page_size, page_token). Use OAuth2 Bearer token.

5. Format response: table (columns: id, direction, channel, state, timestamp, snippet) or raw JSON. Display pagination token if present.

6. On success display "✅ Messages listed" with count. Handle errors (404, 403, etc.) with clear messages.

7. Handle all errors gracefully.

## Examples

```
/sinch-api-messages-list --channel=SMS --page-size=10
/sinch-api-messages-list --contact-id=CONTACT_ID --format=json
/sinch-api-messages-list -c WHATSAPP -n 20 -f table
```

## API Reference

- **MCP Tool**: (list-messages or equivalent if available)
- **API**: Conversation API Messages list/retrieve operations
- **Documentation**: https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/

## Notes

- messages_source parameter may be needed (DISPATCH vs CONVERSATION) depending on app configuration.
- Use page_token from response for next page.