--- title: Create Chat | API Docs --- POST /api/partner/v2/chats Select code sample cURL (shell:curl) ``` const url = 'https://api.linqapp.com/api/partner/v2/chats'; const options = { method: 'POST', headers: { 'X-LINQ-INTEGRATION-TOKEN': '', 'Content-Type': 'application/json' }, body: '{"send_from":"+15175269229","chat":{"display_name":"Sample Chat","phone_numbers":["+13343284472","+13344713465"]},"message":{"text":"Hello! This is a sample message from Linq API v2.","idempotency_key":"msg-2024_01-23_abc123"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ``` curl --request POST \ --url https://api.linqapp.com/api/partner/v2/chats \ --header 'Content-Type: application/json' \ --header 'X-LINQ-INTEGRATION-TOKEN: ' \ --data '{ "send_from": "+15175269229", "chat": { "display_name": "Sample Chat", "phone_numbers": [ "+13343284472", "+13344713465" ] }, "message": { "text": "Hello! This is a sample message from Linq API v2.", "idempotency_key": "msg-2024_01-23_abc123" } }' ``` - Production server api.linqapp.com/api/partner/v2/chats Creates a new chat with the specified phone numbers, or returns an existing chat if one already exists with the same participants. At least one phone number must be provided. **Note:** This endpoint uses “find or create” logic: - If a chat already exists with these participants, returns the existing chat (which may have many messages) - If no chat exists, creates a new chat with your initial message (will have `message_count: 1`) ## Authorizations - **[ApiKeyAuth](/v2/api/#apikeyauth/index.md)** ## Request Body required Media type application/json object **send\_from** required Phone number to send from. This must be one of your organization’s Linq phone numbers. string **chat** required object **display\_name** Display name for the chat (optional) string **phone\_numbers** required Phone numbers to include in the chat Array\ \>= 1 items **message** required Initial message to send when creating the chat object **text** required Message text content string **idempotency\_key** Optional unique key to prevent duplicate messages. Must be alphanumeric and may include hyphens and underscores. If a message with this key was already sent, returns the existing message. string /^\[a-zA-Z0-9\_-]+$/ **attachments** Optional file attachments to upload with the message. Files are uploaded as part of the multipart/form-data request. Include one field per file. Omit this field if not attaching files. Array\ **attachment\_urls** Optional URLs of files to attach to the message. The API will download files from these URLs (must be publicly accessible). Uses a 30-second timeout per download. Can be used together with direct file uploads via `attachments`. Omit this field if not attaching files via URLs. Array\ ##### Examples Select example basic\_message Basic message without attachments ``` { "send_from": "+15175269229", "chat": { "display_name": "Sample Chat", "phone_numbers": [ "+13343284472", "+13344713465" ] }, "message": { "text": "Hello! This is a sample message from Linq API v2.", "idempotency_key": "msg-2024_01-23_abc123" } } ``` Message with attachment URLs ``` { "send_from": "+15175269229", "chat": { "phone_numbers": [ "+13343284472" ] }, "message": { "text": "Here are the documents you requested.", "attachment_urls": [ "https://example.com/document.pdf", "https://example.com/image.jpg" ] } } ``` Message with direct file uploads For direct file uploads, use multipart/form-data. The attachments field accepts binary file data. Note: This is a simplified example. In actual implementation, use multipart/form-data with binary file data. ``` { "send_from": "+15175269229", "chat": { "phone_numbers": [ "+13343284472" ] }, "message": { "text": "Sending files directly", "attachments": [ "" ] } } ``` ## Responses ### 200 Chat created successfully (or existing chat returned if already exists) Media type application/json object **data** object **id** integer **display\_name** string **service** string Allowed values: iMessage SMS RCS **group** boolean **chat\_handles** Array\ object **id** integer **phone\_number** The phone number or email identifier for this participant string **service** The messaging service for this handle string Allowed values: iMessage SMS RCS **joined\_at** string format: date-time **chat\_messages** The initial message that was sent when creating the chat object **id** integer **text** string **sent\_at** string format: date-time **delivered\_at** Timestamp when message was delivered. Initially null when message is pending, populated once delivered. string format: date-time nullable **delivery\_status** Current delivery status. Starts as “pending”, changes to “delivered” once successfully delivered. string Allowed values: pending delivered rate\_limit\_exceeded paused **is\_read** boolean **attachments** Array of attachments if any were included Array\ object **id** Unique identifier for the attachment string format: uuid **url** string **filename** string **mime\_type** string **file\_size** integer ##### Example ``` { "data": { "id": 45, "display_name": "John Doe", "service": "iMessage", "group": false, "chat_handles": [ { "id": 123, "phone_number": "+15551234567", "service": "iMessage", "joined_at": "2025-05-21T15:30:00.000-05:00" }, { "id": 124, "phone_number": "+15559876543", "service": "iMessage", "joined_at": "2025-05-21T15:30:00.000-05:00" } ], "chat_messages": { "id": 16470817, "text": "Hello! This is a sample message from Linq API v2.", "sent_at": "2025-10-23T13:07:55.019-05:00", "delivered_at": null, "delivery_status": "pending", "is_read": false, "attachments": [ { "id": "abc12345-1234-5678-9abc-def012345678", "url": "https://storage.googleapis.com/linq-files/attachments/abc123.pdf", "filename": "document.pdf", "mime_type": "application/pdf", "file_size": 12345 } ] } } } ``` ### 400 Bad request - Invalid or missing parameters (client-side error). Please verify all required parameters are included and properly formatted. Media type application/json Standard error format used by most endpoints (render\_error format) object **errors** Array\ object **status** integer **code** string **title** string **detail** string ##### Example ``` { "errors": [ { "status": 400, "code": "missing_phone", "title": "Missing Phone", "detail": "Missing required parameter: send_from" } ] } ``` ### 422 Validation error Media type application/json Standard error format used by most endpoints (render\_error format) object **errors** Array\ object **status** integer **code** string **title** string **detail** string ##### Example ``` { "errors": [ { "status": 422, "code": "invalid_params", "title": "Invalid Params", "detail": "Phone number is required" } ] } ```