---
title: "Create or find chat"
method: POST
path: "/api/profiles/{profile_id}/chats"
tags: ["Direct Messages"]
---

# Create or find chat

`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

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.

## Query parameters

- `profile_group_id` string

## Headers

- `Idempotency-Key` string

## Request body

- DmChatCreateRequest: Payload for idempotently creating (or finding) a chat by participant.
  - `participant_external_id` string, 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_username` string: Display username for the participant
  - `participant_name` string: Display name for the participant
  - `placement_id` string: 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 `200`

Chat already existed and is returned (idempotent).

- DmChat: A 1:1 conversation between a profile and a participant.
  - `id` string: Chat hashid
  - `profile_id` string: Profile hashid this chat belongs to
  - `platform` 'facebook' | 'instagram' | 'telegram' | 'bluesky': Network ID
  - `participant_external_id` string: Platform-native participant ID
  - `participant_username` string, nullable: Participant's username (when known)
  - `participant_name` string, nullable: Participant's display name (when known)
  - `participant_avatar_url` string, nullable: Stable storage URL of the participant's profile picture (null until fetched)
  - `external_conversation_id` string, nullable: Platform's native conversation ID (when known)
  - `last_inbound_at` string, nullable: ISO 8601 timestamp of last inbound message
  - `last_outbound_at` string, nullable: ISO 8601 timestamp of last outbound message
  - `last_message_at` string, nullable: ISO 8601 timestamp of last message in either direction
  - `archived` boolean: Bluesky only — whether the chat is muted/archived
  - `metadata` DmChatMetadata, nullable: Platform-specific information about the participant, fetched asynchronously when the chat is first created and refreshed at most once per hour on inbound messages. Keys are only present when the platform returns a value — treat missing keys as unknown, not false.
    - `page_id` string: Facebook — Page ID this chat is owned by (required for sending)
    - `participant_fetched_at` string: ISO 8601 timestamp of the last recipient-info refresh
    - `language_code` string: Telegram — IETF language tag reported by Telegram for the user
    - `muted` boolean: Bluesky — whether the conversation is muted/archived
    - `is_verified_user` boolean: Instagram — participant has a verified account
    - `is_user_follow_business` boolean: Instagram — participant follows the business profile
    - `is_business_follow_user` boolean: Instagram — the business profile follows the participant
    - `follower_count` integer: Instagram — participant's follower count
    - `referral` object: Latest ig.me / m.me link referral (latest referral wins)
      - `ref` string
      - `source` string
      - `type` string
      - `received_at` string
    - `last_referral_at` string: ISO 8601 timestamp of the latest referral (opens the 24-hour messaging window)
    - `thread_control` object: Facebook & Instagram — which Meta app controls the conversation, once known. See Thread control.
      - `owner_app_id` string, nullable: Meta app ID that controls the conversation; null while idle (or when another app took it without Postproxy seeing it).
      - `expires_at` string, nullable: ISO 8601 time the owner's control lapses.
      - `updated_at` string: ISO 8601 time the value was last recorded.
  - `created_at` string: ISO 8601 timestamp of chat creation
  - `external_placement_id` string, nullable: The placement the chat runs on — the phone number id on WhatsApp, the Page id on Facebook chats that have one. Null otherwise.
  - `group` boolean: True when the chat is a WhatsApp group rather than a 1:1 conversation.
  - `within_messaging_window` boolean: 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.

## Other responses

- `201`: New chat created.
- `400`: Missing required parameters.
- `401`: Invalid, missing, or insufficient API key permissions.
- `404`: Resource does not exist or is not accessible.
- `422`: Validation failed.

---

[API](https://skmtc.dev/postproxy/apis/postproxy-social-media-api.md) - [All operations](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/revisions/d54482ac4ce7?raw)