List Messages

curl --request GET \
  --url https://api.photon.codes/v1/projects/{id}/messages \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.photon.codes/v1/projects/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "content": {
        "format": "plain",
        "text": "Hello from Photon.",
        "type": "text"
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "id": "pho_msg_00000000000000000000000001",
      "metadata": {},
      "platform": "whatsapp",
      "projectId": "pho_prj_00000000000000000000000001",
      "sentBy": {
        "details": {
          "resourceId": "pho_res_00000000000000000000000001",
          "type": "dedicated"
        },
        "handle": "+14155550123",
        "id": "pho_usr_00000000000000000000000001",
        "kind": "agent",
        "metadata": {},
        "platform": "whatsapp",
        "projectId": "pho_prj_00000000000000000000000001"
      },
      "space": {
        "details": {},
        "id": "pho_spc_00000000000000000000000001",
        "kind": "direct",
        "metadata": {},
        "participantIds": [
          "pho_usr_00000000000000000000000001",
          "pho_usr_00000000000000000000000002"
        ],
        "platform": "whatsapp",
        "projectId": "pho_prj_00000000000000000000000001"
      },
      "status": "dispatched",
      "timestamps": {
        "dispatchedAt": "2026-01-01T00:00:00.000Z"
      },
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

{
  "code": "INVALID_PAGE_TOKEN",
  "status": 400,
  "title": "Invalid Page Token",
  "type": "https://photon.codes/docs/problems/invalid-page-token"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "status": 503,
  "title": "Upstream Service Unavailable",
  "type": "https://photon.codes/docs/problems/upstream-unavailable"
}

{
  "code": "UPSTREAM_TIMEOUT",
  "status": 504,
  "title": "Upstream Service Timeout",
  "type": "https://photon.codes/docs/problems/upstream-timeout"
}

GET

projects

{id}

messages

List Messages

curl --request GET \
  --url https://api.photon.codes/v1/projects/{id}/messages \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.photon.codes/v1/projects/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "content": {
        "format": "plain",
        "text": "Hello from Photon.",
        "type": "text"
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "id": "pho_msg_00000000000000000000000001",
      "metadata": {},
      "platform": "whatsapp",
      "projectId": "pho_prj_00000000000000000000000001",
      "sentBy": {
        "details": {
          "resourceId": "pho_res_00000000000000000000000001",
          "type": "dedicated"
        },
        "handle": "+14155550123",
        "id": "pho_usr_00000000000000000000000001",
        "kind": "agent",
        "metadata": {},
        "platform": "whatsapp",
        "projectId": "pho_prj_00000000000000000000000001"
      },
      "space": {
        "details": {},
        "id": "pho_spc_00000000000000000000000001",
        "kind": "direct",
        "metadata": {},
        "participantIds": [
          "pho_usr_00000000000000000000000001",
          "pho_usr_00000000000000000000000002"
        ],
        "platform": "whatsapp",
        "projectId": "pho_prj_00000000000000000000000001"
      },
      "status": "dispatched",
      "timestamps": {
        "dispatchedAt": "2026-01-01T00:00:00.000Z"
      },
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

{
  "code": "INVALID_PAGE_TOKEN",
  "status": 400,
  "title": "Invalid Page Token",
  "type": "https://photon.codes/docs/problems/invalid-page-token"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "status": 503,
  "title": "Upstream Service Unavailable",
  "type": "https://photon.codes/docs/problems/upstream-unavailable"
}

{
  "code": "UPSTREAM_TIMEOUT",
  "status": 504,
  "title": "Upstream Service Timeout",
  "type": "https://photon.codes/docs/problems/upstream-timeout"
}

Authorizations

Authorization

string

header

required

Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.

Path Parameters

string

required

Pattern: ^pho_prj_[0-7][0-9a-hjkmnp-tv-z]{25}$

Query Parameters

createdBefore

string<date-time>

Exclusive upper bound on createdAt, RFC 3339. Cannot combine with updatedAt bounds.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

createdSince

string<date-time>

Inclusive lower bound on createdAt, RFC 3339. Cannot combine with updatedAt bounds.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

direction

enum<string>

Message origin: received or dispatched, including later delivery outcomes

Available options:

received,

sent

excludeContentTypes

string

Comma-separated content types to exclude from resource-scoped Message lists and counts. Requires resourceId. A group is excluded when group is selected or all of its parts are excluded; retained Messages are unchanged. Supported values: attachment, group, message.delete, message.read, poll, poll.update, poll.vote, reaction, space.participants.update, space.typing.update, text, text.update, voice.

Maximum string length: 1024

order

enum<string>

Direction along orderBy; desc, the default, is newest first

Available options:

asc,

desc

orderBy

enum<string>

Sort timestamp; defaults to the filtered timestamp, otherwise created_at. Must match the time bounds.

Available options:

created_at,

updated_at

pageSize

integer

Items per page. A value above 200 returns at most 200 items.

Required range: 0 <= x <= 9007199254740991

pageToken

string

Token from nextPageToken. Keep the same Project and query.

Required string length: 1 - 4096

Pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$

perspectiveUserId

string

Selects this User's sent or received Messages. Requires spaceId; cannot combine with resourceId.

Pattern: ^pho_usr_[0-7][0-9a-hjkmnp-tv-z]{25}$

platform

enum<string>

Restricts the page to one platform

Available options:

sms,

email,

whatsapp,

whatsapp_business,

imessage,

telegram

resourceId

string

Resource associated with the Message when sent or received. Can combine with spaceId, but not perspectiveUserId.

Pattern: ^pho_res_[0-7][0-9a-hjkmnp-tv-z]{25}$

spaceId

string

Requires resourceId or perspectiveUserId. User perspectives use created_at order and exclude time bounds and platform filters.

Pattern: ^pho_spc_[0-7][0-9a-hjkmnp-tv-z]{25}$

updatedBefore

string<date-time>

Exclusive upper bound on updatedAt, RFC 3339. Cannot combine with createdAt bounds.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

updatedSince

string<date-time>

Inclusive lower bound on updatedAt, RFC 3339. Cannot combine with createdAt bounds.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Response

A page of Messages in the requested order.

items

object[]

required

Unsupported platforms and records with unsupported data are omitted.

Show child attributes

Example:

{
  "content": {
    "format": "plain",
    "text": "Hello from Photon.",
    "type": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "id": "pho_msg_00000000000000000000000001",
  "metadata": {},
  "platform": "whatsapp",
  "projectId": "pho_prj_00000000000000000000000001",
  "sentBy": {
    "details": {
      "resourceId": "pho_res_00000000000000000000000001",
      "type": "dedicated"
    },
    "handle": "+14155550123",
    "id": "pho_usr_00000000000000000000000001",
    "kind": "agent",
    "metadata": {},
    "platform": "whatsapp",
    "projectId": "pho_prj_00000000000000000000000001"
  },
  "space": {
    "details": {},
    "id": "pho_spc_00000000000000000000000001",
    "kind": "direct",
    "metadata": {},
    "participantIds": [
      "pho_usr_00000000000000000000000001",
      "pho_usr_00000000000000000000000002"
    ],
    "platform": "whatsapp",
    "projectId": "pho_prj_00000000000000000000000001"
  },
  "status": "dispatched",
  "timestamps": {
    "dispatchedAt": "2026-01-01T00:00:00.000Z"
  },
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

nextPageToken

string

Continue with this token, even if items is empty. Omitted when no more pages remain.

Required string length: 1 - 4096

Pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$

⌘I

Get started

Problems

Endpoints

Event Delivery WebSocket

Event schemas

List Messages

Authorizations

Path Parameters

Query Parameters

Response