Hand a conversation to a person

POST/api/v2/agent-mailboxes/:id/escalate

Puts the conversation in the Action center as an escalation, with your reason.

Needs an API key with the send scope. Scopes

Parameters

Path

idstringrequired

The agent mailbox id, or me.

Body

thread_idstringrequired

The conversation.

reasonstringrequired

Why a person should take over, up to 2,000 characters.

Notes

thread_id must be a conversation the mailbox has received mail in.
Returns 202 with the item_id.

curl -X POST "https://api.koltrix.com/api/v2/agent-mailboxes/me/escalate" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
  "reason": "The customer is asking for a refund."
}'

const res = await fetch("https://api.koltrix.com/api/v2/agent-mailboxes/me/escalate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
    "reason": "The customer is asking for a refund."
  }),
});

console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.koltrix.com/api/v2/agent-mailboxes/me/escalate",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
    },
    json={
        "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
        "reason": "The customer is asking for a refund."
    },
)
print(res.status_code, res.json())

package main

import (
	"strings"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := strings.NewReader(`{
  "thread_id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
  "reason": "The customer is asking for a refund."
}`)
	req, _ := http.NewRequest("POST", "https://api.koltrix.com/api/v2/agent-mailboxes/me/escalate", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOLTRIX_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

<?php

$ch = curl_init("https://api.koltrix.com/api/v2/agent-mailboxes/me/escalate");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("KOLTRIX_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "thread_id" => "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
        "reason" => "The customer is asking for a refund.",
    ]),
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $response;

Success.

{
  "item_id": "5c4b3a29-1807-4e6d-9c8b-7a6958473625"
}

The body is not valid JSON, or a field has the wrong type.

{
  "error": "invalid body"
}

The API key is missing, malformed, unknown or revoked.

{
  "error": "invalid or revoked api key"
}

The key is valid but does not have the send scope.

{
  "error": "missing permission: send"
}

No such record in this workspace.

{
  "error": "thread not found"
}

More than 60 requests a minute on this key. Wait Retry-After seconds. No code field.

Retry-After: 60

{
  "error": "rate limit exceeded — 60 requests per minute per API key"
}

Try it below with your own key. Every sample reads the key from KOLTRIX_API_KEY.

Try it

Send this request from your browser.

Input

What you send

API key

Stays in this browser tab (sessionStorage) and goes only to api.koltrix.com. Create one under Settings → API keys.

Requests are real and this one changes data in your workspace. Koltrix has no test mode, so use a dedicated key with only the permissions you need and revoke it when you are done.

idstringrequired

thread_idstringrequired

reasonstringrequired

Request body · JSON

Valid JSON. The fields above and this editor stay in sync.

POSThttps://api.koltrix.com/api/v2/agent-mailboxes/me/escalate

Output

What comes back

The response appears here.
Press Send request.