Create Chat
const url = 'https://api.linqapp.com/api/partner/v2/chats';const options = { method: 'POST', headers: { 'X-LINQ-INTEGRATION-TOKEN': '<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: <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" } }'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
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Phone number to send from. This must be one of your organization’s Linq phone numbers.
object
Display name for the chat (optional)
Phone numbers to include in the chat
Initial message to send when creating the chat
object
Message text content
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.
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.
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.
Examples
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": [ "<binary file data>" ] }}Responses
Section titled “ Responses ”Chat created successfully (or existing chat returned if already exists)
object
object
object
The phone number or email identifier for this participant
The messaging service for this handle
The initial message that was sent when creating the chat
object
Timestamp when message was delivered. Initially null when message is pending, populated once delivered.
Current delivery status. Starts as “pending”, changes to “delivered” once successfully delivered.
Array of attachments if any were included
object
Unique identifier for the attachment
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 } ] } }}Bad request - Invalid or missing parameters (client-side error). Please verify all required parameters are included and properly formatted.
Standard error format used by most endpoints (render_error format)
object
object
Example
{ "errors": [ { "status": 400, "code": "missing_phone", "title": "Missing Phone", "detail": "Missing required parameter: send_from" } ]}Validation error
Standard error format used by most endpoints (render_error format)
object
object
Example
{ "errors": [ { "status": 422, "code": "invalid_params", "title": "Invalid Params", "detail": "Phone number is required" } ]}