API del Team

Il tuo team è composto da chiunque lavori all’interno del tuo account oltre a te — amministratori, agenti e visualizzatori in sola lettura — oltre agli inviti che hai inviato e ai dipartimenti in cui li organizzi. L’API del Team è la versione programmatica di Impostazioni → Team: aggiungi e rimuovi persone, imposta ciò che ognuno di loro può vedere e fare, invia e sollecita inviti e gestisci i dipartimenti.

Tutti gli endpoint sottostanti sono relativi all’URL di base https://api.youraiconnector.com/v1. Per la versione dashboard di tutto ciò che è presente in questa pagina, consulta Gestione del Team.

Autenticazione: questi endpoint richiedono una persona che abbia effettuato l’accesso

Questa è l’unica parte dell’API che una chiave API non può utilizzare. Ogni endpoint /team, ad eccezione di quelli relativi ai dipartimenti, deve essere chiamato con un token ID Firebase da una sessione con accesso effettuato:

Authorization: Bearer <Firebase ID token>

Invia una chiave API e la richiesta verrà rifiutata con un 401:

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

Il motivo è che questi endpoint decidono cosa fare in base a chi ha effettuato l’accesso: il tuo ruolo, il limite massimo di ciò che ti è consentito concedere a qualcun altro e se stai attualmente lavorando all’interno di un altro account. Una chiave API è un’integrazione, non una persona, quindi non c’è nessuno a cui applicare tali regole.

In pratica, ciò significa che l’API del Team è destinata a un’app di prima parte con un utente Your AI Connector che ha effettuato l’accesso (vedi Autenticazione → Token ID Firebase). Un’integrazione server-to-server non può gestire i membri del team: non c’è modo di creare uno di questi token dall’esterno dell’app.

L’eccezione: i quattro endpoint dei dipartimenti sono normali endpoint API. Accettano la tua chiave API esattamente come il resto dell’API, così come una sessione con accesso effettuato.

Ogni risposta in questa pagina segue il solito inviluppo: success: true più i campi dell’endpoint al livello principale, oppure success: false con error e error_code quando qualcosa va storto.

Ruoli e autorizzazioni

Ogni membro del team ha un ruolo, che imposta il suo accesso predefinito in 12 aree dell’app. È quindi possibile sovrascrivere le singole aree.

Ruolo	Valore	Riepilogo
Admin	`admin`	Tutto tranne le azioni a livello di fatturazione del proprietario.
Editor	`editor`	Può creare e modificare elementi. Mostrato come Agente nell’app.
Viewer	`viewer`	Sola lettura.

Ogni area è impostata su uno dei quattro livelli: none (nascosto), view (sola lettura), edit (crea e modifica), full (inclusa l’eliminazione).

Area	Admin	Editor	Viewer
`campaigns`	full	edit	view
`contacts`	full	edit	view
`messages`	full	edit	view
`appointments`	full	edit	view
`settings`	edit	view	none
`billing`	edit	none	none
`team_management`	edit	none	none
`analytics`	full	view	view
`phone_numbers`	edit	none	none
`integrations`	edit	none	none
`faqs`	full	edit	view
`daily_summaries`	full	view	view

Per discostarsi dalle impostazioni predefinite del ruolo, invia permission_overrides — una matrice di oggetti { "area": ..., "level": ... }. Ogni voce sostituisce l’impostazione predefinita del ruolo per quella specifica area; tutto ciò che non elenchi mantiene l’impostazione predefinita del ruolo.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Chi può chiamare questi endpoint

Il proprietario dell’account può sempre fare tutto.
Un membro del team necessita di team_management a view per leggere l’elenco dei membri e la lista degli inviti, e di edit per aggiungere, modificare, sospendere, rimuovere, invitare, annullare o reinviare. Gli amministratori hanno edit per impostazione predefinita; editor e visualizzatori hanno none, quindi di default solo gli amministratori possono gestire il team.
Nessuno può concedere un accesso superiore al proprio. Se provi a dare a qualcuno un livello che tu stesso non possiedi — o a modificare, sospendere o rimuovere qualcuno il cui accesso è già più ampio del tuo — la richiesta viene rifiutata con 403 e un messaggio che indica l’area.

L’oggetto membro del team

GET /team/members restituisce uno di questi per ogni membro:

Campo	Tipo	Descrizione
`member_uid`	string	L’ID utente del membro. Questo è il `{memberUid}` nei percorsi sottostanti.
`account_owner_uid`	string	L’account di cui sono membri.
`member_email`	string	Il loro indirizzo email.
`member_display_name`	string	Il nome visualizzato per loro nell’app.
`role`	string	`admin`, `editor` o `viewer`.
`permission_overrides`	array	Le loro eccezioni per area. `[]` quando utilizzano esclusivamente le impostazioni predefinite del ruolo.
`status`	string	`active` o `suspended`.
`auto_assign_enabled`	boolean \| null	Se i nuovi contatti possono essere assegnati automaticamente a loro. `null` significa mai modificato, che si comporta come `true`.
`created_by`	string	Chi li ha aggiunti.
`created_at`	string \| null	Timestamp ISO 8601.
`updated_at`	string \| null	Timestamp ISO 8601.

I membri rimossi non vengono restituiti — l’elenco include solo i membri attivi e sospesi.

I limiti di visibilità sono di sola scrittura in questo contesto. contact_scope, contact_scope_axes e sub_account_access (vedi Limitare ciò che un membro può vedere) possono essere impostati durante la creazione, l’aggiornamento e l’invito, ma questo endpoint non li restituisce.

Elenca i membri del team

GET /team/members

Restituisce l’elenco dei membri più il conteggio dei posti del tuo piano, così puoi mostrare “3 posti su 5” e sapere quando un invito sta per essere rifiutato.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Risposta

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit è null quando il tuo piano non ha un limite di posti. seats_used conta solo i membri attivi — sospendere o rimuovere qualcuno libera immediatamente il suo posto.

Aggiungi direttamente un membro del team

POST /team/members

Inserisce qualcuno nel tuo team immediatamente, senza un invito.

Questo non invia alcuna email. Nessuno viene avvisato dell’avvenuta aggiunta e, se non possedevano già un login Your AI Connector, l’account creato per loro non ha password, quindi non possono accedere finché non la reimpostano. Usa Invia un invito a meno che tu non abbia un tuo metodo per informare la persona e farla accedere.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`email`	Sì	L’indirizzo email del membro del team.
`display_name`	Sì	Il nome visualizzato per loro nell’app.
`role`	Sì	`admin`, `editor` o `viewer`.
`permission_overrides`	No	Eccezioni per area rispetto ai valori predefiniti del ruolo.
`contact_scope`	No	`all` o `assigned` — vedi Limitare ciò che un membro può vedere.
`contact_scope_unassigned`	No	Con `assigned`, consenti loro di vedere anche i contatti non ancora assegnati.
`contact_scope_axes`	No	Limitali ad agenti, canali o dipartimenti specifici.
`sub_account_access`	No	Solo per agenzie — quali sotto-account cliente possono aprire.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Risposta — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

Stato	Quando
`400`	`email`, `display_name` o `role` manca, il ruolo non è uno dei tre, o hai provato ad aggiungere te stesso.
`403`	Non hai il permesso di gestire il team, o hai provato a concedere un accesso superiore al tuo.
`409`	Quella persona è già un membro attivo del tuo team.
`429`	I posti del team nel tuo piano sono esauriti.

Aggiungere qualcuno che era stato precedentemente sospeso o rimosso lo ripristina invece di fallire.

Aggiorna un membro del team

PATCH /team/members/{memberUid}

Modifica il ruolo, i permessi, la visibilità, l’accesso ai clienti o la partecipazione all’assegnazione automatica dei contatti di un membro. Invia solo i campi che desideri modificare; tutto ciò che ometti manterrà il suo valore attuale.

Campi della richiesta

Campo	Descrizione
`role`	`admin`, `editor` o `viewer`.
`permission_overrides`	Sostituisce l’intero elenco di eccezioni. Invia `[]` per riportarli ai valori predefiniti del ruolo.
`status`	È accettato solo `active`, per riattivare un membro sospeso. Per sospendere qualcuno, usa l’endpoint di sospensione.
`auto_assign_enabled`	`true` o `false`.
`contact_scope`	`all` o `assigned`.
`contact_scope_unassigned`	`true` o `false`.
`contact_scope_axes`	Vedi Limitare ciò che un membro può vedere.
`sub_account_access`	Solo per agenzie.

Questo è l’unico endpoint in cui null significa “cancella”. Inviare "contact_scope": null, "contact_scope_axes": null o "sub_account_access": null rimuove completamente quel limite e riporta il membro a vedere tutto. Durante la creazione e l’invito, null significa semplicemente “non fornito”.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Risposta

{
  "success": true,
  "message": "Team member updated successfully."
}

Stato	Quando
`400`	Un valore `status` o `auto_assign_enabled` non valido, o hai provato a riattivare un membro che era stato rimosso (i membri rimossi devono essere re-invitati).
`403`	Non hai il permesso, o la modifica comporterebbe la modifica o la creazione di un accesso più ampio del tuo.
`404`	Membro del team inesistente.

Sospendi un membro del team

POST /team/members/{memberUid}/suspend

Sospende qualcuno: mantengono il loro posto nel team ma perdono l’accesso. Usa questo invece della rimozione quando la pausa è temporanea — falli rientrare con PATCH /team/members/{memberUid} e {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta

{
  "success": true,
  "message": "Team member suspended successfully."
}

Un membro sospeso libera il proprio posto, così puoi invitare qualcun altro al suo posto. Il loro accesso termina al prossimo aggiornamento del token di sessione, il che può richiedere fino a un’ora — rimuovili invece se hai bisogno che sia immediato.

Stato	Quando
`400`	Hai provato a sospendere il proprietario dell’account, o un membro già sospeso o rimosso.
`403`	Il loro accesso è più ampio del tuo.
`404`	Membro del team inesistente.

Rimuovi un membro del team

DELETE /team/members/{memberUid}

Rimuove una persona dal tuo team e libera il suo posto. Verrà disconnessa e perderà l’accesso al tuo account; il suo login personale rimane invariato.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta

{
  "success": true,
  "message": "Team member removed successfully."
}

La rimozione è permanente dal tuo lato: un membro rimosso non può essere riattivato tramite l’endpoint di aggiornamento; invitalo di nuovo se cambi idea. Il suo indirizzo email viene inoltre rimosso dalla lista delle notifiche del tuo account.

Stato	Quando
`400`	Hai provato a rimuovere il proprietario dell’account.
`403`	Il suo accesso è più ampio del tuo.
`404`	Membro del team inesistente.

Limitare ciò che un membro può vedere

Tre campi opzionali, accettati su aggiunta, aggiornamento e invito, determinano quanta parte dell’account una persona può vedere. Si sommano: un membro limitato su più di uno è limitato da tutti loro.

contact_scope — all (l’impostazione predefinita: ogni contatto e conversazione) o assigned (solo quelli assegnati a loro). Con assigned, aggiungi "contact_scope_unassigned": true per consentire loro di vedere anche i contatti non ancora assegnati a nessuno.

contact_scope_axes — li limita ad agenti, canali o dipartimenti specifici:

Campo	Tipo	Descrizione
`agents`	string[]	ID agente. Vedono solo le chat indirizzate a uno di questi agenti. Massimo 200.
`channels`	string[]	Nomi dei canali — `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `instagram_private`, `messenger`, `facebook`, `chat_widget`, `telegram`, `line`, `viber`, `tiktok`, `imessage`, `email`, `linkedin`, `skool`, `custom`, `custom_channel`. Massimo 200.
`departments`	string[]	ID dipartimento (vedi Dipartimenti). Vedono solo i lead archiviati sotto di essi. Massimo 200.
`include_unrouted`	boolean	Con `agents` impostato, mostra anche le chat che nessun agente gestisce. Disattivato per impostazione predefinita. Ignorato quando `agents` è vuoto.
`include_undepartmented`	boolean	Con `departments` impostato, mostra anche le chat che non appartengono a nessun dipartimento. Disattivato per impostazione predefinita. Ignorato quando `departments` è vuoto.

Gli ID di agenti e dipartimenti non vengono controllati al momento del salvataggio: un ID inesistente semplicemente non corrisponde a nulla, il che si traduce in una casella di posta vuota anziché in un errore. I nomi dei canali vengono controllati: uno non riconosciuto viene rifiutato con 400.

Nessuno di questi tre può essere impostato sul proprietario dell’account: tale richiesta viene rifiutata con 400.

Elenco inviti

GET /team/invites

Gli inviti che hai inviato, dal più recente al meno recente, così puoi vedere chi non ha ancora accettato.

Parametri di query

Parametro	Obbligatorio	Descrizione
`status`	No	Restituisce solo gli inviti in questo stato: `pending`, `accepted`, `declined`, `cancelled` o `expired`.

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

Il token di invito non viene mai restituito: esiste solo nell’email che è stata inviata.

Invia un invito

POST /team/invites

Invia via email un invito a qualcuno per unirsi al tuo team. Questo è il modo abituale per aggiungere un membro del team: cliccano sul link, effettuano l’accesso come se stessi e accettano. Se non hanno ancora un account Your AI Connector, ne viene creato uno per loro e l’email li guida nella creazione di una password.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`email`	Sì	Dove inviare l’invito.
`role`	Sì	`admin`, `editor` o `viewer`.
`permission_overrides`	No	Eccezioni per area, applicate nel momento in cui accettano.
`contact_scope`	No	Applicato quando accettano.
`contact_scope_unassigned`	No	Applicato quando accettano.
`contact_scope_axes`	No	Applicato quando accettano.
`sub_account_access`	No	Solo per agenzie. Applicato quando accettano.

Impostare le autorizzazioni in anticipo significa non dover modificare il membro in seguito: tutto viene copiato nella sua iscrizione quando accetta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Risposta — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Cose da pianificare

Gli inviti scadono dopo 7 giorni. Un invito scaduto può essere reinviato, il che fa ripartire un nuovo periodo di 7 giorni.
Gli inviti in sospeso occupano un posto. A differenza dell’aggiunta diretta di un membro, il controllo dei posti qui conta i membri attivi più gli inviti in sospeso, quindi un account con tutti i posti occupati viene rifiutato prima che l’email venga inviata.
20 inviti al giorno, conteggiati per account sia per l’invio che per il reinvio.

Stato	Quando
`400`	`email` manca o il ruolo non è valido.
`403`	Non hai l’autorizzazione per gestire il team, o hai tentato di concedere un accesso superiore al tuo.
`409`	Esiste già un invito in sospeso per quell’email, o quella persona è già nel tuo team.
`429`	I posti del team del tuo piano sono esauriti, o hai raggiunto il limite di 20 inviti al giorno. Il messaggio `error` indica quale.

Annulla un invito

DELETE /team/invites/{inviteId}

Ritira un invito prima che venga accettato. Il link nell’email smetterà di funzionare.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta

{
  "success": true,
  "message": "Team invite cancelled."
}

È possibile annullare sia gli inviti pending che quelli expired. Un invito già accettato, rifiutato o annullato restituisce 400; uno non tuo restituisce 403; un ID sconosciuto restituisce 404.

Reinvia un invito

POST /team/invites/{inviteId}/resend

Invia nuovamente l’email di invito, nel caso in cui sia andata persa o sia finita nello spam. Funziona con gli inviti pending e expired e reimposta la scadenza a 7 giorni da oggi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta

{
  "success": true,
  "message": "Team invite resent successfully."
}

La nuova email contiene un nuovo link, e anche il vecchio link continua a funzionare, così una persona che trova la prima email in seguito non rimane bloccata. Il reinvio viene conteggiato nel limite giornaliero di 20 invii, e riattivare un invito scaduto ricontrolla i tuoi posti disponibili: un piano completo verrà rifiutato con 429.

Accetta un invito

POST /team/invites/accept

Accetta un invito utilizzando il token presente nell’email di invito, aggiungendo la persona che ha effettuato l’accesso al team di quell’account.

Questa è un’azione legata alla tua identità. Accedi come te stesso: l’operazione viene deliberatamente rifiutata con 403 mentre stai lavorando all’interno dell’account di qualcun altro.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`invite_token`	Sì	Il token dal link dell’email di invito.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Risposta

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

Stato	Quando
`400`	`invite_token` manca, o l’invito è per il tuo stesso account.
`403`	La sessione è attiva all’interno di un altro account, o l’invito è stato inviato a un indirizzo email diverso da quello con cui hai effettuato l’accesso.
`404`	L’invito non esiste o è già stato utilizzato.
`429`	I posti dell’account si sono esauriti tra l’invio dell’invito e la tua accettazione.
`504`	L’invito è scaduto. Chiedi al mittente di reinviarlo.

Rifiuta un invito

POST /team/invites/decline

Rifiuta un invito utilizzando il token presente nell’email. Come per l’accettazione, questa è un’azione legata alla tua identità e viene rifiutata mentre stai lavorando all’interno di un altro account.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Risposta

{
  "success": true,
  "message": "Team invite declined."
}

Reparti

Un dipartimento è un gruppo nominato del tuo team: Vendite, Assistenza clienti, Risorse umane. Assegna a un lead un team proprietario, può gestire autonomamente nuove conversazioni e può essere utilizzato per limitare ciò che un membro può vedere.

Questi quattro endpoint richiedono una chiave API. A differenza del resto di questa pagina, si autenticano come ogni altro endpoint nell’API (vedi Autenticazione). Funziona anche una sessione con accesso effettuato: la lettura richiede contacts su view, mentre la creazione, la modifica o l’eliminazione richiedono team_management su edit.

L’oggetto dipartimento

Campo	Tipo	Descrizione
`id`	string	L’ID del dipartimento. Usalo in `contact_scope_axes.departments` e nei percorsi sottostanti.
`name`	string	Il nome del team. Fino a 60 caratteri, univoco nell’account.
`color`	string \| null	Colore d’accento come `#rrggbb`, o `null`.
`member_uids`	string[]	I membri del team in questo dipartimento. Può includere il proprietario dell’account.
`auto_assign_enabled`	boolean	Indica se un lead archiviato in questo dipartimento viene assegnato anche a qualcuno al suo interno. `false` significa che il dipartimento lavora da una coda condivisa.
`routing_agents`	string[]	Le nuove conversazioni gestite da questi Agenti IA vengono archiviate automaticamente in questo dipartimento. Se vuoto, non c’è alcuna regola per l’agente.
`routing_channels`	string[]	Le nuove conversazioni su questi canali vengono archiviate qui automaticamente. Se vuoto, non c’è alcuna regola per il canale.
`created_by`	string \| null	Chi lo ha creato.

Quando sia routing_agents che routing_channels sono impostati, una conversazione deve corrispondere a entrambi per essere archiviata qui: è così che assegni a un team “l’agente di supporto, ma solo su WhatsApp”.

Un account può avere fino a 50 dipartimenti.

Elenca dipartimenti

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Crea un dipartimento

POST /team/departments

Campi della richiesta

Campo	Obbligatorio	Descrizione
`name`	Sì	Fino a 60 caratteri. Non deve corrispondere a un dipartimento esistente.
`color`	No	`#rrggbb` esadecimale, o `null`.
`member_uids`	No	Chi ne fa parte. Ogni UID deve essere il proprietario dell’account o un membro del team attivo.
`auto_assign_enabled`	No	Predefinito a `true`.
`routing_agents`	No	ID degli agenti le cui nuove chat finiscono qui.
`routing_channels`	No	Nomi dei canali le cui nuove chat finiscono qui: stesso vocabolario di `contact_scope_axes.channels`.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Risposta — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Stato	Quando
`400`	`name` manca o è troppo lungo, `color` non è `#rrggbb`, un nome di canale non è riconosciuto, un UID elencato non è un membro attivo di questo team, o hai già 50 dipartimenti.
`409`	Esiste già un dipartimento con quel nome.

Aggiorna un dipartimento

PATCH /team/departments/{departmentId}

Modifica un dipartimento. Vengono modificati solo i campi inviati.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Risposta

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

L’invio di campi non riconosciuti restituisce 400; un dipartimento sconosciuto restituisce 404; un nome che entra in conflitto con un altro dipartimento restituisce 409.

Eliminare un dipartimento

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "deleted": "dep_abc123"
}

L’eliminazione di un dipartimento a cui qualcuno è limitato viene rifiutata. La risposta 400 indica i membri la cui visibilità è limitata a tale dipartimento, in modo da poter prima modificare il loro ambito. Questa è una scelta deliberata: rimuovere silenziosamente la limitazione fornirebbe loro l’intera base clienti senza alcun avviso.

I contatti archiviati in un dipartimento eliminato non vengono riscritti: semplicemente smettono di mostrare un dipartimento e, la volta successiva in cui li archivi, l’impostazione verrà applicata.

Controlla le tue autorizzazioni

GET /team/permissions

Restituisce ciò che la persona che ha effettuato l’accesso può fare nell’account in cui sta lavorando attualmente. Usalo per nascondere i pulsanti che un membro non può utilizzare, invece di lasciare che scopra il limite tramite un errore.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Risposta: il proprietario dell’account

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Risposta: un membro del team che lavora all’interno di un account

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role è owner quando la persona che ha effettuato l’accesso è il proprietario dell’account; altrimenti è il suo ruolo nel team. member è presente solo in modalità team e contiene contact_scope, contact_scope_unassigned e contact_scope_axes quando la sua appartenenza li prevede.

Token di sessione

Cinque endpoint creano un token di accesso una tantum per passare da un account all’altro. Rispondono tutti allo stesso modo:

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

Il token viene scambiato per una sessione con l’SDK client di Firebase. Non è una chiave API e non può essere inviato come tale, motivo per cui questi endpoint sono utili solo all’interno di un’applicazione proprietaria.

Endpoint	Cosa fa	Corpo
`POST /team/tokens/team-member`	Consente a un membro del team di iniziare a lavorare all’interno di un account a cui appartiene.	`account_owner_uid` (obbligatorio)
`POST /team/tokens/return-from-team`	Riporta l’utente al proprio account.	—
`POST /team/tokens/assist`	Consente al personale Your AI Connector di aprire l’account di un cliente per fornire assistenza. Solo per il personale.	`customerUid`
`POST /team/tokens/return-to-admin`	Termina una sessione di assistenza e riporta il personale al proprio account.	—
`POST /team/tokens/agency-assist`	Consente a un’agenzia di aprire uno dei suoi sotto-account cliente oppure, se chiamato senza, di tornare all’account dell’agenzia.	`subAccountUid` (facoltativo)

Ciascuno rifiuta con 403 quando la sessione non ne ha il diritto: non è un membro di quell’account, non è parte dello staff, quel sotto-account non appartiene alla tua agenzia o non ti è stato concesso, oppure la sessione non è attualmente nella modalità prevista dall’endpoint.

Assegna un ruolo sulla piattaforma

POST /team/users/{targetUid}/role

Imposta il ruolo piattaforma di un utente: User, Dev, Support o Agency. Non si tratta dell’appartenenza al team: è il tipo di account Your AI Connector che una persona possiede.

Questo endpoint è limitato allo staff Your AI Connector e l’ultimo Dev rimanente non può essere declassato. Elencato per completezza; non fa parte della gestione del proprio team.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

Stato	Quando
`400`	`role` manca o non è uno dei quattro, oppure questa azione rimuoverebbe l’ultimo `Dev`.
`403`	Non sei parte dello staff, o la sessione sta operando all’interno di un altro account.
`404`	Utente inesistente.

Errori dell’API del team

Gli endpoint del team restituiscono il pacchetto di errore standard, sempre con error_code insieme allo stato HTTP:

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

Stato	Quando si verifica su un endpoint del team
`400`	Un campo obbligatorio manca o non è valido, oppure l’azione non è consentita in questo stato (riattivazione di un membro rimosso, sospensione del proprietario, eliminazione di un dipartimento a cui qualcuno è limitato).
`401`	Hai inviato una chiave API a un endpoint che richiede una persona autenticata — vedi Autenticazione.
`403`	Non hai il permesso `team_management`, la modifica supera il tuo livello di accesso, o l’azione viene rifiutata mentre operi all’interno di un altro account.
`404`	Membro, invito, dipartimento o utente inesistente.
`409`	Già membro del team, esiste già un invito in sospeso, o esiste già un dipartimento con quel nome.
`429`	I posti nel team sono esauriti, è stato raggiunto il limite di 20 inviti al giorno, o hai raggiunto il limite di frequenza dell’API.
`504`	L’invito che hai tentato di accettare è scaduto.

I codici condivisi che ogni endpoint può restituire — 429 (limite di frequenza) e 500 — sono elencati con indicazioni su come riprovare in Errori e Paginazione.

Correlati

Gestione del Team — le stesse funzionalità nella dashboard, con screenshot.
Autenticazione — come inviare un token ID Firebase invece di una chiave API.
API Contatti — i contatti a cui si applicano i limiti di visibilità di un membro.

API del Team #

Autenticazione: questi endpoint richiedono una persona che abbia effettuato l’accesso #

Ruoli e autorizzazioni #

L’oggetto membro del team #

Elenca i membri del team #

Aggiungi direttamente un membro del team #

Aggiorna un membro del team #

Sospendi un membro del team #

Rimuovi un membro del team #

Limitare ciò che un membro può vedere #

Elenco inviti #

Invia un invito #

Annulla un invito #

Reinvia un invito #

Accetta un invito #

Rifiuta un invito #

Reparti #

Elenca dipartimenti #

Crea un dipartimento #

Aggiorna un dipartimento #

Eliminare un dipartimento #

Controlla le tue autorizzazioni #

Token di sessione #

Assegna un ruolo sulla piattaforma #

Errori dell’API del team #

Correlati #

API del Team

Autenticazione: questi endpoint richiedono una persona che abbia effettuato l’accesso

Ruoli e autorizzazioni

L’oggetto membro del team

Elenca i membri del team

Aggiungi direttamente un membro del team

Aggiorna un membro del team

Sospendi un membro del team

Rimuovi un membro del team

Limitare ciò che un membro può vedere

Elenco inviti

Invia un invito

Annulla un invito

Reinvia un invito

Accetta un invito

Rifiuta un invito

Reparti

Elenca dipartimenti

Crea un dipartimento

Aggiorna un dipartimento

Eliminare un dipartimento

Controlla le tue autorizzazioni

Token di sessione

Assegna un ruolo sulla piattaforma

Errori dell’API del team

Correlati