Skip to content

Quickstart

This page walks through the fastest path from “blank workspace” to “first conversation in your inbox.” It exists to demonstrate the patterns we’ll use for every getting-started page: callouts, tabbed code blocks, and cross-links to API references.

1. Verify your credentials

Every API call requires an API key. You can find yours under Workspace → Developer → API keys. Hit /v1/users/me to confirm the key works and see which workspace it’s scoped to.

export FOYER_API_KEY="sk_live_…"
curl https://api.foyersupport.com/v1/users/me \
  -H "Authorization: Bearer $FOYER_API_KEY"

const res = await fetch("https://api.foyersupport.com/v1/users/me", {
  headers: { Authorization: `Bearer ${process.env.FOYER_API_KEY}` },
});
const me = await res.json();
console.log(me.user_id);

import os, httpx

res = httpx.get(
    "https://api.foyersupport.com/v1/users/me",
    headers={"Authorization": f"Bearer {os.environ['FOYER_API_KEY']}"},
)
print(res.json()["user_id"])

2. Open a conversation

A conversation is the unit of work and always belongs to a customer on a specific channel. Grab a channel_id from GET /v1/channels (or create one under Settings → Channels), create or look up the customer, then open the conversation with an initial_message.

# 1. Create or look up the customer
CUSTOMER_ID=$(curl -s https://api.foyersupport.com/v1/customers \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Alice", "primary_email": "alice@example.com"}' \
  | jq -r .customer_id)

# 2. Open the conversation on an existing channel
curl https://api.foyersupport.com/v1/conversations \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"customer_id\": \"$CUSTOMER_ID\",
    \"subject\": \"Hello from the API\",
    \"channel_type\": \"email\",
    \"channel_id\": \"email-main\",
    \"initial_message\": {
      \"body_text\": \"Hi! Just checking things out.\",
      \"author_type\": \"customer\",
      \"author_id\": \"$CUSTOMER_ID\"
    }
  }"

const headers = {
  Authorization: `Bearer ${process.env.FOYER_API_KEY}`,
  "Content-Type": "application/json",
};

const customer = await fetch("https://api.foyersupport.com/v1/customers", {
  method: "POST",
  headers,
  body: JSON.stringify({
    display_name: "Alice",
    primary_email: "alice@example.com",
  }),
}).then((r) => r.json());

const conversation = await fetch(
  "https://api.foyersupport.com/v1/conversations",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      customer_id: customer.customer_id,
      subject: "Hello from the API",
      channel_type: "email",
      channel_id: "email-main",
      initial_message: {
        body_text: "Hi! Just checking things out.",
        author_type: "customer",
        author_id: customer.customer_id,
      },
    }),
  },
).then((r) => r.json());

console.log(conversation.conversation_id);

headers = {
    "Authorization": f"Bearer {os.environ['FOYER_API_KEY']}",
    "Content-Type": "application/json",
}

customer = httpx.post(
    "https://api.foyersupport.com/v1/customers",
    headers=headers,
    json={"display_name": "Alice", "primary_email": "alice@example.com"},
).json()

res = httpx.post(
    "https://api.foyersupport.com/v1/conversations",
    headers=headers,
    json={
        "customer_id": customer["customer_id"],
        "subject": "Hello from the API",
        "channel_type": "email",
        "channel_id": "email-main",
        "initial_message": {
            "body_text": "Hi! Just checking things out.",
            "author_type": "customer",
            "author_id": customer["customer_id"],
        },
    },
)
print(res.json()["conversation_id"])

3. Watch it land

Open the inbox at app.foyersupport.com — the conversation appears in real time over the WebSocket fanout (no polling, no refresh).

Next

REST API reference — the full surface
Webhooks — react to inbox events from your own systems
MCP server — operate Foyer from any MCP-aware agent