POpostproxy
Direct Messages

Create or find chat

Idempotently creates a chat for a (profile, participant_external_id) pair. If a chat with that participant already exists, the existing chat is returned and any provided participant fields are updated.

post/api/profiles/{profile_id}/chats

Request

  • Base URL
    https://api.postproxy.dev
  • URL
    https://api.postproxy.dev/api/profiles/{profile_id}/chats
  • Auth
    HTTP bearer

Query parameters

profile_group_idstring

Profile group context for the request. Optional when the API key is scoped to a profile group (that group is used automatically); with a full-access key, defaults to the first profile group in the account.

Headers

Idempotency-Keystring

Optional idempotency key (up to 255 characters; a UUID is ideal). Retrying a successful write with the same key replays the original response (with an Idempotent-Replay: true header) instead of executing again. Stored responses are kept for 24 hours; only 2xx responses are stored.

Request body

participant_external_idstring required

Platform participant ID (Instagram-scoped user ID for IG, PSID for Facebook, DID for Bluesky, the phone number for WhatsApp — any format, reduced to digits)

participant_usernamestring

Display username for the participant

participant_namestring

Display name for the participant

placement_idstring

Required on WhatsApp — the phone number id the conversation runs on. Optional on Facebook, where it records the Page an API-created chat sends from.

Response

Chat already existed and is returned (idempotent).

idstring

Chat hashid

profile_idstring

Profile hashid this chat belongs to

platform'facebook' | 'instagram' | 'telegram' | 'bluesky'

Network ID

participant_external_idstring

Platform-native participant ID

participant_usernamestring nullable

Participant's username (when known)

participant_namestring nullable

Participant's display name (when known)

participant_avatar_urlstring nullable

Stable storage URL of the participant's profile picture (null until fetched)

external_conversation_idstring nullable

Platform's native conversation ID (when known)

last_inbound_atstring nullable

ISO 8601 timestamp of last inbound message

last_outbound_atstring nullable

ISO 8601 timestamp of last outbound message

last_message_atstring nullable

ISO 8601 timestamp of last message in either direction

archivedboolean

Bluesky only — whether the chat is muted/archived

created_atstring

ISO 8601 timestamp of chat creation

external_placement_idstring nullable

The placement the chat runs on — the phone number id on WhatsApp, the Page id on Facebook chats that have one. Null otherwise.

groupboolean

True when the chat is a WhatsApp group rather than a 1:1 conversation.

within_messaging_windowboolean

WhatsApp only. Whether a free-form send is currently allowed — true for 24 hours after the customer’s last inbound message or referral. Outside it, send an approved template.

Changes

No recorded changes to this operation across all 1 revision of this API.