SparrowDesk
Conversations

Create a conversation

POST
/conversations

Authorization

AuthorizationBearer <token>

In: header

Request Body

descriptionstring

Opening message body (HTML). Inline images hosted on supported source platforms are fetched and re-hosted automatically, with their links rewritten.

subjectstring
priority?string

Priority level (defaults to Medium if not provided)

Value in"Low" | "Medium" | "High" | "Urgent"
source?string

Conversation source (defaults to Call if not provided)

Value in"Mail" | "Call" | "API"
brand_id?number

Brand ID (defaults to account's default brand if not provided)

status?string

Status (defaults to Open if not provided)

Value in"Open" | "Pending" | "Resolved" | "Closed"
requested_bystring

Requested by email or phone number

requested_by_firstname?string

First name applied to the requester contact only when it is created. If a contact with this email/phone already exists, it is reused and its name is not changed.

requested_by_lastname?string

Last name applied to the requester contact only when it is created (same create-only behaviour as requested_by_firstname).

assignee?string
Formatemail
team_id?number
created_at?integer

The time the conversation was created (epoch seconds). If not provided, the current time is used.

resolved_at?integer

The time the conversation was resolved (epoch seconds). Only allowed when status is Resolved or Closed, and must be >= created_at.

skip_notifications?boolean

Option to disable notifications when a Conversation is created. Defaults to false.

custom_fields?
tags?array<string>

Tag labels to attach to the conversation. Tags that don't exist are created. Also useful for recording the channel/origin (e.g. "chat", "email").

attachments?

Files fetched from these URLs and attached to the conversation's opening message. If a file can't be fetched, the conversation is still created and that file is skipped.

Response Body

application/json

application/json

application/json

curl -X POST "https://app.sparrowdesk.com/v1/conversations" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "subject": "string",    "requested_by": "string"  }'
{
  "data": {
    "id": 12345,
    "brand": "Support Brand",
    "brand_id": 1,
    "source": "Mail",
    "status": "Open",
    "priority": "High",
    "created_at": 1672531200,
    "first_response_time": null,
    "resolution_time": null,
    "due": 1672617600,
    "first_response_due": 1672538400,
    "requested_by_email": "[email protected]",
    "requested_by_id": 67890,
    "assigned_to_member_id": 123,
    "assigned_to_team_id": 456,
    "last_updated_at": 1672535400,
    "subject": "Payment issue with order #12345",
    "description_html": "<p>I'm having trouble with my payment...</p>",
    "description_text": "I'm having trouble with my payment...",
    "attachments": [
      "https://cdn.example.com/receipt.pdf"
    ],
    "tags": [
      {
        "id": 1,
        "label": "billing"
      },
      {
        "id": 2,
        "label": "urgent"
      }
    ],
    "custom_fields": [
      {
        "id": 9250,
        "value": "ORD-12345",
        "option_ids": null
      },
      {
        "id": 9260,
        "value": "premium",
        "option_ids": null
      },
      {
        "id": 9270,
        "value": "Bug, Billing",
        "option_ids": [
          7790,
          7791
        ]
      }
    ],
    "properties": {
      "request_language": "English",
      "browser_timezone": "Asia/Calcutta",
      "browser": "Chrome",
      "device": "mac OS 10.15.7",
      "ip_address": "192.168.1.1",
      "country": "India",
      "region": "Tamil Nadu > Chennai",
      "referral_url": "http://localhost:9091/",
      "utm_source": "",
      "utm_medium": "",
      "utm_campaign": "",
      "utm_content": "",
      "utm_term": ""
    }
  }
}
{
  "error": {
    "message": "Invalid field values"
  }
}
{
  "error": {
    "message": "Error while creating conversation"
  }
}