API di integrazione Ciamem

Identità della chiave

Verifica che la chiave funzioni: ritorna tenant, pacchetto, permessi e limiti.

curl "https://www.ciamem.com/api/v1/me" \
  -H "Authorization: Bearer ciamem_live_…"

Elenco dei contatti

La rubrica del tenant. Filtri: q (numero, nome o azienda), companyId.

Parametri: q · companyId · limit · offset

curl "https://www.ciamem.com/api/v1/contacts" \
  -H "Authorization: Bearer ciamem_live_…"

Dettaglio di un contatto

Il contatto è identificato dal numero di telefono (o dall'id chat per i clienti Telegram).

curl "https://www.ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…"

Crea o aggiorna un contatto

Se il contatto non esiste viene creato.

{
  "name": "Mario Rossi",
  "company": "Acme SRL",
  "companyId": "id azienda in anagrafica",
  "notes": "Cliente storico",
  "language": "it"
}

curl -X PUT "https://www.ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Mario Rossi","company":"Acme SRL","companyId":"id azienda in anagrafica","notes":"Cliente storico","language":"it"}'

Elimina un contatto

Il bot non lo riconoscerà più alla chiamata successiva.

curl -X DELETE "https://www.ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…"

Elenco dei clienti (aziende)

Filtri: q (nome o P.IVA), status (regolare | bloccato).

Parametri: q · status · limit · offset

curl "https://www.ciamem.com/api/v1/companies" \
  -H "Authorization: Bearer ciamem_live_…"

Crea un cliente

Lo stato "bloccato" impedisce al bot di aprire ticket per i contatti di quest'azienda.

{
  "name": "Acme SRL",
  "vat": "01234567890",
  "status": "regolare",
  "phone": "",
  "email": "",
  "address": "",
  "notes": ""
}

curl -X POST "https://www.ciamem.com/api/v1/companies" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Acme SRL","vat":"01234567890","status":"regolare","phone":"","email":"","address":"","notes":""}'

Dettaglio di un cliente

curl "https://www.ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Aggiorna un cliente

L'azienda predefinita "(anonimo)" non è modificabile.

{
  "name": "Acme SRL",
  "status": "bloccato"
}

curl -X PUT "https://www.ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Acme SRL","status":"bloccato"}'

Elimina un cliente

I contatti associati tornano sull'azienda "(anonimo)". I ticket già aperti restano.

curl -X DELETE "https://www.ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Ricerca ticket

Filtri: status (aperto | assegnato | chiuso | aperti = tutti i non chiusi), companyId, agent, from, to (YYYY-MM-DD), q. Per la sincronizzazione incrementale usa updatedSince (ISO): ricevi solo i ticket cambiati.

Parametri: status · companyId · agent · from · to · q · updatedSince · limit · offset

curl "https://www.ciamem.com/api/v1/tickets" \
  -H "Authorization: Bearer ciamem_live_…"

Apre un ticket

Il ticket viene annunciato agli agenti su Telegram col bottone di presa in carico, come quelli aperti dal bot. Intestazione Idempotency-Key: un retry dopo un timeout non crea un doppione.

{
  "text": "Stampante fiscale in blocco",
  "companyId": "id azienda (facoltativo)",
  "contactName": "Mario Rossi",
  "contactKey": "+393331234567",
  "priority": "normale | alta"
}

curl -X POST "https://www.ciamem.com/api/v1/tickets" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"text":"Stampante fiscale in blocco","companyId":"id azienda (facoltativo)","contactName":"Mario Rossi","contactKey":"+393331234567","priority":"normale | alta"}'

Dettaglio di un ticket

Accetta l'id interno o il codice (TK-0001). Include la timeline e i metadati delle foto allegate.

curl "https://www.ciamem.com/api/v1/tickets/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Aggiunge una nota al ticket

La nota entra nella timeline ed è visibile agli agenti.

{
  "text": "Intervento pianificato per lunedì"
}

curl -X POST "https://www.ciamem.com/api/v1/tickets/:id/entries" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"text":"Intervento pianificato per lunedì"}'

Aggiorna un ticket (priorità, chiusura)

Chiudendo il ticket il cliente viene avvisato sul canale chat da cui l'ha aperto. Accetta anche PUT.

{
  "status": "chiuso",
  "note": "Sostituita la scheda",
  "priority": "alta"
}

curl -X PATCH "https://www.ciamem.com/api/v1/tickets/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"status":"chiuso","note":"Sostituita la scheda","priority":"alta"}'

Elenco degli agenti

Gli agenti Telegram del tenant e il loro stato (in turno o in pausa).

curl "https://www.ciamem.com/api/v1/agents" \
  -H "Authorization: Bearer ciamem_live_…"

Mette un agente in pausa o lo rimette in turno

In pausa non riceve nuovi ticket né notifiche, ma continua a gestire i ticket già suoi. Aggiungere o rimuovere agenti resta un'operazione da console.

{
  "paused": true
}

curl -X PATCH "https://www.ciamem.com/api/v1/agents/:chatId" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"paused":true}'