Skip to content
ReplycoReplycoAPI

Open a ticket for a customer

When a customer contacts you through your own system, you can open a ticket for them in Replyco so that your team handles it with the rest of their work. You create the customer, add their order when the conversation is about one, and open the ticket with the customer’s message. The ticket belongs to your custom integration.

Before you start

Section titled “Before you start”
Requirement Where to get it
An access token Sign in as a Replyco user of your company; see Authentication.
A custom integration’s id Tickets can be opened only on a custom integration. Register one, or list yours, as in Connect your own system as a custom integration.
The base URL https://open-api.replyco.com

How it works

Section titled “How it works”
  1. Create the customer.
  2. Add their order (optional).
  3. Open the ticket.
sequenceDiagram
  participant app as Your app
  participant api as Replyco API
  app->>api: POST /openapi/customer
  api-->>app: Create the customer
  opt Add their order
    app->>api: POST /openapi/order
    api-->>app: Add their order
  end
  app->>api: POST /openapi/thread/create
  api-->>app: Open the ticket

Step by step

Section titled “Step by step”

1. Create the customer

Section titled “1. Create the customer”

Call POST /openapi/customer with your custom integration’s id in integrationId, marketplace set to 20 (custom integration), and the customer’s details. marketCustomerId holds your own id for the customer.

Terminal window
curl -X POST https://open-api.replyco.com/openapi/customer \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"integrationId": "3f1c2a9e-6b4d-4c8e-9f2a-1d5e7b3c9a06", "marketplace": 20, "firstName": "Tom", "lastName": "Baker", "email": "tom.baker@example.com", "phone": "+44 7700 900123", "marketCustomerId": "acme-customer-20931", "notes": [{"note": "Prefers email over phone."}]}'

The response is the customer as stored. Its id is the customerId of the next steps.

Every call creates a new customer, even with the same details. If the customer may already be in Replyco, search for them first with GET /openapi/customer/paged?term=acme-customer-20931; term matches names, email, phone and marketCustomerId.

2. Add their order (optional)

Section titled “2. Add their order (optional)”

Skip this step when the ticket is not about an order. Otherwise call POST /openapi/order with the same integrationId, the customerId from step 1, and the order’s details.

Terminal window
curl -X POST https://open-api.replyco.com/openapi/order \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"integrationId": "3f1c2a9e-6b4d-4c8e-9f2a-1d5e7b3c9a06", "customerId": "a4e1c7b9-3d5f-4a2e-8b6c-9f1d3e7a5c28", "marketOrderId": "SO-20931", "orderTotalAmount": 42.0, "orderCurrency": "GBP", "paid": true}'
{
  "integrationId": "3f1c2a9e-6b4d-4c8e-9f2a-1d5e7b3c9a06",
  "customerId": "a4e1c7b9-3d5f-4a2e-8b6c-9f1d3e7a5c28",
  "marketOrderId": "SO-20931",
  "orderTotalAmount": 42.0,
  "orderCurrency": "GBP",
  "paid": true,
  "shippingService": "Royal Mail Tracked 48",
  "shipmentAddress": {
    "addressLine1": "12 Example Street",
    "city": "Leeds",
    "postalCode": "LS1 4AP",
    "country": "GB"
  }
}

The order is stored for that customer. Orders lists every field, including line items.

3. Open the ticket

Section titled “3. Open the ticket”

Call POST /openapi/thread/create with a subject, your custom integration’s id in accountId, the customerId from step 1 and the customer’s message. To hand the ticket to a particular agent, add task.userId; agents’ ids come from GET /openapi/user/id_name, which answers with an object that maps each user’s id to their name.

Terminal window
curl -X POST https://open-api.replyco.com/openapi/thread/create \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"subject": "Where is my order SO-20931?", "accountId": "3f1c2a9e-6b4d-4c8e-9f2a-1d5e7b3c9a06", "customerId": "a4e1c7b9-3d5f-4a2e-8b6c-9f1d3e7a5c28", "message": {"htmlBody": "<p>My order has not arrived yet. Can you check?</p>"}, "task": {"userId": "9b3e5f17-2c8d-4a6e-b1f9-7e4d2c6a8b53"}}'
{
  "subject": "Where is my order SO-20931?",
  "accountId": "3f1c2a9e-6b4d-4c8e-9f2a-1d5e7b3c9a06",
  "customerId": "a4e1c7b9-3d5f-4a2e-8b6c-9f1d3e7a5c28",
  "message": { "htmlBody": "<p>My order has not arrived yet. Can you check?</p>" },
  "task": { "userId": "9b3e5f17-2c8d-4a6e-b1f9-7e4d2c6a8b53" }
}

The response is the new ticket, with its id.

  • The message is recorded as the customer’s message.
  • Without task, the ticket is assigned to the user you sign in as. An agent you assign is notified.
  • Without subject, the ticket is called “No Subject”. It starts as Open unless you send another status.
  • Attachments go in message.attachments: a fileName with its extension and the base64-encoded content in data, up to 10 MB per file and 25 MB per message. Executable and script files are refused.
  • Every call opens a new ticket, so do not repeat a call that succeeded.

What can go wrong

Section titled “What can go wrong”
Step Status Meaning What to do
any 401 The access token is missing or has expired. Refresh the token; see Authentication.
any 429 Too many calls to this operation. Slow down; see Rate limits.
3 400 accountId is not a custom integration, the request has no message, or an attachment breaks a rule. Read the error text. Use a custom integration’s id, include message, and check the attachment rules above.
Section titled “Related”