All help articles

supporto.city: the help desk for teams

supporto.city sells Zappocity's help desk to other businesses. It is the same support system Zappocity answers its own customers with (see the Zappocity help desk), split into desks: each team that subscribes gets a desk of its own with its own queues, tickets, canned replies, help center and mail settings. Zappocity's own help desk is simply the first desk. Nothing on one desk can be seen or changed from another, and tickets are numbered per desk (a team's first ticket is T-1).

Building it was in steps (docs/plans/supporto.md): desks, the plans and per-seat prices, subscribing a team, the agent app at /desk with its API (api/desk.yaml), each desk's own mail with agents' addresses, each desk's own host, its customer pages, and signing up. It stays coming in the catalog until you make it available under Products: then its page invites teams in and they make desks themselves.

Plans

Prices are per agent (seat) and month; billed monthly they are 20% more.

Change prices, limits and features under Products → supporto.city like any product's (limits: agents, queues, and agentsBySeats, 1 when the seats bought also limit the agents). Features are switched on or off for one team on its subscription's Features. The features beyond the help center are promised by the plans and arrive with the agent app.

Signing up

supporto.city's own host (its site host, supporto.city) shows its page: what it is, the plans with their prices and features straight from the catalog (so a price changed under Products shows at once), and Start free. While the product is coming the page says "Coming soon" and nobody can make a desk themselves.

Once it is available, Start free leads to the Zappocity account page (signing up or in there), where Help desks → Make a help desk makes an organization the person owns, subscribed to the Free plan; the desk is ready at once with them as its administrator. A person can make up to three desks this way (staff can make more). The same card lists the desks they work, with links to each desk and its customer page.

Owners and billing members change the plan and seats on the organization's subscription on the account page, and whether it is billed monthly or yearly. A dearer plan and more seats are invoiced at once for the rest of the period (the difference, in proportion to the time left); a cheaper plan or fewer seats take effect without a refund; a new billing period starts at the next renewal; a plan or seats the desk does not fit are refused with the reason.

Subscribing a team

On the organization's page, Subscribe to supporto.city with a plan and, on a paid plan, the number of seats (agents):

corpsuite zappocity subscribe ORG-ID product=supporto plan=team seats:=5

This makes the team's desk, named after the organization, with an address name taken from it (acme-support-co, or acme-support-co-2 when taken) and one queue, Support, whose tickets are numbered T-1 onwards. The subscription's Resource is the desk's id.

• Changing the plan is refused while the desk has more agents or queues than the new plan allows; remove some first.
• Fewer seats than the desk has agents are refused the same way. More seats are billed at once for the rest of the period (see Billing).
• Canceling suspends the desk and unlinks it from the subscription; its tickets, agents and settings are kept, and it stays the organization's.

The desk's host

Each desk also has a host of its own: <desk>.<supporto.city's host> (acme-support-co.supporto.city). Its address opens the desk's customer page; agents work at /desk there. Point a wildcard DNS record (*.supporto.city) at the server. corpsuited gets each desk host its certificate when first asked; zappocityd needs a wildcard certificate in CORPSUITE_TLS_CERT.

Agents sign in there with their Zappocity account: Sign in takes them to the Zappocity account page (where they may already be signed in) and back to the desk with a session of its own. The way back is a one-time code for that desk's host only, usable once within two minutes and only in the browser that started, so a link cannot sign someone in as someone else. Two-step sign-in carries over.

The desk's customers

On the desk's host, customers have:

• **/help, the desk's own help center: the articles and FAQs its administrators write under Help center**, with "Contact support" leading to the customer page.
• **/support**, the customer page: they sign in with their Zappocity account (made on Zappocity if they have none) and see their requests to this desk, open a new one in the desk's public queues, reply and add people to the replies, as the queue allows.
• Links in the desk's mail lead there (to sign in, or straight to the request without signing in where the queue allows).

Requests to a desk are the desk's only: they never show on Zappocity's own account page, and Zappocity's never on a desk's.

The desk's mail

Each desk's mail is at <desk>.<supporto.city's host>, the host being supporto.city's site host under Products (supporto.city in production; never written into the code). When a desk is made it gets a team of its own on Mailocity with that domain, and each queue a mailbox there: support@acme-support-co.supporto.city. A queue an administrator adds later gets its mailbox too.

• Mail to a queue's address opens a ticket when the queue takes mail (set under Queues), and replies to its notifications land on their ticket, as on Zappocity's own desk.
• Customers are told about new tickets and replies from the queue's address, under the desk's name ("Acme Support"), with links to the desk's customer page.
• If supporto.city had no host when the desk was made, an administrator sets the mail up later under Queues → Set up mail (or POST /api/desk/{desk}/mail), as they can when it failed.

The help desk mail job reads every desk's queue mailboxes each minute.

Agents' addresses

Every agent also has a name on the desk's domain, taken from their Zappocity email (amy@acme-support-co.supporto.city; amy2 when two agents share a name). The desk's administrators choose what these are, under Queues → Mail:

• Ticket addresses (to start with): mail to an agent's address goes to the desk's first queue (Support) and opens or continues tickets there, like mail to the queue's own address.
• Mailboxes: each agent gets a mailbox of their own on Mailocity, and signs in to it in webmail with their Zappocity account (no separate password). An agent who also has a mailbox at their Zappocity address is signed in to that one first; choosing between them comes later. Once the desk's mail is set up, mailboxes cannot go back to ticket addresses, as they hold the agents' mail.

Taking an agent off the desk takes their ticket address away, or suspends their mailbox, keeping its mail. A queue cannot be named after an agent's address. The Agents page shows each agent's address.

Agents

Agents are Zappocity accounts. Each desk has administrators, who run its queues, agents, canned replies and help center, and agents, who answer tickets; both count against the plan and seats. The organization's first owner is the desk's first administrator. An administrator adds someone by the confirmed email of their Zappocity account (PUT /api/desk/{desk}/agents), as an agent or administrator; a desk always keeps one administrator.

Agents work the desk at **/desk/{desk}** (the desk's address name; /desk lists every desk they work), signed in with their Zappocity account: the same help desk pages Zappocity's staff have in the admin panel (the overview of queues and urgent tickets, search, tickets with replies, notes, canned replies and macros, follow-ups, the help center and keyboard shortcuts), showing only that desk, plus Agents. Administrators also see Queues. The pages call the desk API at /api/desk/{desk} (api/desk.yaml). Someone who is not the desk's agent gets "no such desk". An agent sees the queues that list them, or every queue when a queue lists nobody; administrators see every queue. A suspended desk can be read but not changed.