Reply to or close a conversation from your app

Every write needs expected_version. The version changes when an email or a form submission arrives, and when status, snooze, or assignee change, from the API or from the inbox. Reading the conversation right before you write gives you the current value.

export const base = process.env.INTRAY_API_URL!;
export const auth = { Authorization: `Bearer ${process.env.INTRAY_API_KEY}` };

export async function readConversation(conversationId: string) {
  const response = await fetch(`${base}/conversations/${conversationId}`, {
    headers: auth,
  });
  const result = await response.json();
  if (!response.ok) throw new IntrayError(response.status, result.error);
  return result.conversation as {
    id: string;
    version: string;
    assignee_id: string | null;
    triage: { status: string; snooze_until: number | null };
  };
}

export class IntrayError extends Error {
  constructor(
    public status: number,
    public detail: { code: string; message: string; request_id: string }
  ) {
    super(`${detail.code}: ${detail.message}`);
  }
}

Post the reply with the version you read. Build the Idempotency-Key from the event in your own system, such as the refund ID, so that a retry of the same event sends one email. Use the customer email address your app already has on file for to. The API accepts one recipient.

triage_after_send is preserve by default, which leaves the status as it is. Set it to done when the reply closes the matter, or to todo when someone on the team should follow up.

import { auth, base, IntrayError, readConversation } from "./intray";

export async function replyAboutRefund(refund: {
  id: string;
  conversationId: string;
  customerEmail: string;
  amount: string;
}) {
  const conversation = await readConversation(refund.conversationId);

  const response = await fetch(
    `${base}/conversations/${refund.conversationId}/messages`,
    {
      method: "POST",
      headers: {
        ...auth,
        "Content-Type": "application/json",
        "Idempotency-Key": `refund-reply-${refund.id}`,
      },
      body: JSON.stringify({
        expected_version: conversation.version,
        to: [{ address: refund.customerEmail }],
        text: `This is an automatic update. Your refund of ${refund.amount} was issued today. Reply to this email if anything looks wrong.`,
        triage_after_send: "done",
      }),
    }
  );
  const result = await response.json();
  if (!response.ok) throw new IntrayError(response.status, result.error);
  return result; // { message_id, conversation, delivery, suppressed }
}

A 202 response means Intray queued the email. It does not mean the email was delivered. Check whether an email was delivered covers the delivery states.

Use PATCH when the event needs no message to the customer. Send triage, assignee_id, or both. A request with neither returns 422.

import { auth, base, IntrayError, readConversation } from "./intray";

export async function closeAfterShipment(order: {
  id: string;
  conversationId: string;
}) {
  const conversation = await readConversation(order.conversationId);

  const response = await fetch(
    `${base}/conversations/${order.conversationId}`,
    {
      method: "PATCH",
      headers: {
        ...auth,
        "Content-Type": "application/json",
        "Idempotency-Key": `order-shipped-${order.id}`,
      },
      body: JSON.stringify({
        expected_version: conversation.version,
        triage: { status: "done" },
      }),
    }
  );
  const result = await response.json();
  if (!response.ok) throw new IntrayError(response.status, result.error);
  return result.conversation;
}

triage.status accepts todo, done, snoozed, and spam. With snoozed, also send snooze_until as a future time in Unix milliseconds. A conversation marked done moves back to Todo when the customer writes again. A status change made through the API does not run the rules that fire when a person changes status in the inbox.

assignee_id is the Intray user ID of a current workspace member, or null to unassign. The API has no endpoint that lists members. To get an ID, assign any conversation to that person in the inbox, read the conversation with GET, and copy the assignee_id from the response. Store the ID next to the account owner in your own system.

body: JSON.stringify({
  expected_version: conversation.version,
  assignee_id: account.intrayUserId,
}),

409 version_conflict means the conversation changed after you read it. Usually the customer wrote again or a teammate replied, changed the status, or took the thread. Read the conversation again and decide whether your change still makes sense. If a teammate has replied in the meantime, the automated reply is often no longer needed. When you do send it again, use the new version and a new Idempotency-Key, because the payload is different from the first attempt.

try {
  await replyAboutRefund(refund);
} catch (error) {
  if (error instanceof IntrayError && error.detail.code === "version_conflict") {
    // Someone acted on the thread. Hand the decision to a person.
    await flagForReview(refund.id, "Conversation changed before the refund reply was sent");
    return;
  }
  throw error;
}