Foyer API · Recipe

Weekly summary of who called

A plain-text digest of the past week: how many calls Foyer handled, what it did with them, who called most often, and every voicemail. Send it to yourself by email, or paste it into your notes.

You need: a key with calls:read (any plan).

The script

foyer_weekly_summary.py

import os
import time
from collections import Counter
from datetime import datetime, timedelta, timezone

import requests

API = "https://api.hifoyer.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['FOYER_API_KEY']}"}
since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()

calls, cursor = [], None
while True:
    params = {"since": since, "limit": 100, "archived": "include"}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get(f"{API}/calls", headers=HEADERS, params=params, timeout=30)
    if resp.status_code == 429:
        time.sleep(int(resp.headers.get("Retry-After", "5")))
        continue
    resp.raise_for_status()
    page = resp.json()
    calls += [c for c in page["data"] if not c["self_test"]]
    cursor = page["next_cursor"]
    if not cursor:
        break

who = lambda c: c["caller"]["name"] or c["caller"]["number"] or "Withheld number"
print(f"Foyer: {len(calls)} calls in the last 7 days\n")
for label, n in Counter(c["outcome_label"] for c in calls).most_common():
    print(f"  {n:4}  {label}")
print("\nCalled most often:")
for name, n in Counter(who(c) for c in calls).most_common(5):
    print(f"  {n:4}  {name}")
print("\nVoicemails:")
for c in reversed(calls):
    if c["voicemail"]["state"] in ("transcribed", "audio_only"):
        print(f"  {c['started_at'][:10]}  {who(c)}: {c['summary']}")

Each call's outcome_label says what Foyer did in plain words, such as "Held for your review" or "Sent to voicemail". Test calls you made to your own line (self_test) are left out.

Every Monday

crontab -e

0 8 * * 1 FOYER_API_KEY=fyr_… python3 /path/to/foyer_weekly_summary.py | mail -s "Foyer: last week's calls" [email protected]

Or ask an assistant connected to Foyer: "Summarize last week's calls: who called, what they wanted, and anything I still need to deal with." See Connect Claude or ChatGPT.

Today's numbers in one request

GET /v1/stats returns today's counts (put through, held for review, sent to voicemail, blocked) and totals since you joined, without paging.