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

# Create or find chat

`POST /v1/social/profiles/{profile_id}/chats`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/social/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.

**Billing:** Engagement action (request) · **Rate limit:** 60/min

## Path parameters

- `profile_id` string, required: Profile ID

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object: Payload for idempotently creating (or finding) a chat by participant.
  - `participant_name` string: Display name for the participant
  - `participant_username` string: Display username for the participant
  - `participant_external_id` string, required: Platform participant ID (Instagram-scoped user ID for IG, PSID for Facebook, DID for Bluesky)

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: A 1:1 conversation between a profile and a participant.
    - `id` string: Chat hashid
    - `archived` boolean: Bluesky only — whether the chat is muted/archived
    - `metadata` object, 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.
      - `muted` boolean: Bluesky — whether the conversation is muted/archived
      - `page_id` string: Facebook — Page ID this chat is owned by (required for sending)
      - `referral` object: Latest ig.me / m.me link referral (latest referral wins)
        - `ref` string
        - `type` string
        - `source` string
        - `received_at` string
      - `language_code` string: Telegram — IETF language tag reported by Telegram for the user
      - `follower_count` integer: Instagram — participant's follower count
      - `is_verified_user` boolean: Instagram — participant has a verified account
      - `last_referral_at` string: ISO 8601 timestamp of the latest referral (opens the 24-hour messaging window)
      - `participant_fetched_at` string: ISO 8601 timestamp of the last recipient-info refresh
      - `is_business_follow_user` boolean: Instagram — the business profile follows the participant
      - `is_user_follow_business` boolean: Instagram — participant follows the business profile
    - `platform` 'facebook' | 'instagram' | 'telegram' | 'bluesky': Network ID
    - `created_at` string: ISO 8601 timestamp of chat creation
    - `profile_id` string: Profile hashid this chat belongs to
    - `last_inbound_at` string, nullable: ISO 8601 timestamp of last inbound message
    - `last_message_at` string, nullable: ISO 8601 timestamp of last message in either direction
    - `last_outbound_at` string, nullable: ISO 8601 timestamp of last outbound message
    - `participant_name` string, nullable: Participant's display name (when known)
    - `participant_username` string, nullable: Participant's username (when known)
    - `participant_avatar_url` string, nullable: Stable storage URL of the participant's profile picture (null until fetched)
    - `participant_external_id` string: Platform-native participant ID
    - `external_conversation_id` string, nullable: Platform's native conversation ID (when known)
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)