Integrations

Overview

The screen is in the Integrations menu, with the subtitle Connect ChatISP to your systems. Access requires the Integrations permission in the profile (see Users and profiles).

Other connections to external services live outside this screen: the WhatsApp numbers and the official Meta API (WhatsApp connections), Google Calendar, connected by each user in My account (see Google Calendar), and the system email (see System email).

Ravicor

Ravicor is the network management platform from Ravi Systems. Connected to ChatISP, it is responsible for everything network related in the customer record; the ERP remains the source of registry and billing data.

What the connection enables

• The subscriber network view on the conversation card: concentrator, PPPoE session, OLT and ONU signal, equipment, Wi-Fi, connected devices, outages and reboots (see Customer record: network).
• Actions on the customer equipment: Reboot and Edit Wi-Fi, by the agent or by the AI.
• For the AI, also the speed test and the analysis and change of the Wi-Fi channel, when the installed Ravicor already has these diagnostics.
• Manual customer linking through the registry search (see Manual link).
• The Import from Ravicor button, which brings the ERPs registered in Ravicor into ChatISP.
• While no ERP is registered in ChatISP, customer identification by phone number is done by Ravicor.

Card states

Connect by pairing (recommended)

With pairing, nobody copies any key: ChatISP requests access, someone releases it in Ravicor and the key arrives on its own, stored encrypted. It is not shown on any screen.

1. On the Ravicor card, fill in Ravicor address with the IP or hostname of the server (for example 192.168.0.10). It can also be the full URL. Without a protocol, ChatISP tries HTTPS and, if there is no certificate, HTTP.
2. Click Connect. The card changes to Waiting for release.
3. In Ravicor, open Settings › Integrations and release the ChatISP request.
4. Go back to ChatISP: the screen checks on its own every few seconds and changes to Connected as soon as the request is released, with the notice Integration confirmed. There is no need to reload.

While waiting, Cancel request gives up on the connection. If the request is declined or removed in Ravicor, the card goes back to the start with the notice The connection was removed in Ravicor.

Test and disconnect

• Test connection makes a call to Ravicor and answers Integration confirmed. or Could not connect. Check the address and the key.
• Disconnect asks for the confirmation Disconnect from Ravicor? ChatISP access is cancelled on both sides. ChatISP notifies Ravicor, which deletes the key, and clears the connection on this side. ERPs imported from Ravicor remain registered in ChatISP.
• When the screen opens with the card connected, ChatISP checks whether the connection still exists in Ravicor; if it was removed there, it warns you and returns to the initial state.

Manual configuration

Below the Connect button, Enter the API key manually opens the Address (full URL) and API key fields. The card changes to Configured with the text Configured with a manually entered API key.

ERPs and external systems

The ERPs and external systems card gathers the registry and billing sources for customer service. The ERP is what says who the customer is, what the contract status is and what they owe; ChatISP talks to it directly, with no intermediaries.

The ERP list

Each registered ERP takes one row:

With no ERP, the card shows No ERP connected yet. Add a source or import from Ravicor. Below the ERP list is the table of generic external systems (see External systems).

Which company the ERP serves

With more than one active knowledge base (several companies on the same ChatISP), each row gets the Serves choice: All bases or the name of a base. Tapping saves immediately (Done, the choice applies to the next conversations.). On the numbers of a base, the assistant and the customer card only query its ERPs and the ones that serve all. With a single base, nothing appears and the ERP serves everything. See Several bases: one per company.

Card buttons

• Add source opens the Add external source window, with one card for each certified ERP (IXC Provedor, SGP (TSMX), Hubsoft, Gesprov, ReceitaNet, Pipesoft: Guided setup, in the certified pattern) and the Other system card (Generic API integration).
• Import from Ravicor appears when Ravicor is connected through pairing. See Import ERPs from Ravicor.

Register an ERP

1. In ERPs and external systems, click Add source and choose the ERP.
2. In the Connect ERP window, fill in Name for this connection (how the ERP will appear on the screen and on the customer card) and API address (URL).
3. Fill in the credentials of the chosen ERP (table below).
4. Click Test and connect. ChatISP makes a real call to the ERP before saving: it only saves if the credential works.
5. Once saved, the ERP starts turned on and the first load of the subscriber mirror begins in the background. The screen can be closed: the load continues on its own and the subscriber count grows in the list.

Fields per ERP

Messages when testing

Edit

When editing, the secret fields (token, password, client secret) come empty with the hint Leave blank to keep the current key. If left blank, the saved credential is kept. In Hubsoft, to change the credential, enter Client Secret and User password together. Every edit is validated with a real call before saving, turns the ERP back on and triggers a new mirror load.

Specifics of each ERP

IXC Provedor

• The mirror is built from access logins, contracts, customers, speed groups and sales plans. The plan speed comes from the speed group of the login.
• Periodic synchronization brings only what changed since the previous one. When IXC releases a contract upon payment without marking the change, the Refresh button on the card rereads that customer directly in the ERP.
• Billing: open invoices (up to 100 per customer), last payment, bank slip (boleto), gateway link and Pix copy and paste when the wallet generates Pix, with the QR Code image supplied by IXC itself. ChatISP does not generate or update bank slips in IXC.
• An invoice charged by card or gateway that has not been issued yet arrives without a payment method and appears flagged in the invoices window.
• Trust unblocking by contract, with the days and restrictions configured in IXC. The IXC temporary release is not available through the API.
• Lists titles by due date in its own API, which feeds the automatic billing reminders without an intermediate mirror (Sending automation).

Hubsoft

• OAuth authentication with client ID, client secret, user (email) and password.
• The mirror is built from the services of each customer. Periodic synchronization asks Hubsoft for the services changed since the day of the previous one; the speed comes from the plan text (for example "200 Mbits").
• Billing: up to 50 pending invoices per query, last payment, bank slip digitable line, PDF link and Pix copy and paste when the wallet generates Pix.
• Trust unblocking by service, with the maximum number of days set in the Hubsoft panel.

SGP (TSMX)

• Uses the query routes of the URA category of the SGP API, read only. Token and application must be correct together.
• The API does not offer filtering by date: each synchronization goes through the entire customer listing.
• SGP does not publish the speed as numbers, so the card shows only the plan name.
• Billing: the contract titles, each with the digitable line, bank slip link and Pix copy and paste; the last payment comes from the same query. The card Refresh button rereads the customer directly in SGP.
• Trust unblocking through the SGP URA payment promise (the monthly promise limit is an SGP rule and a refusal comes back explained). Live lookup by CPF/CNPJ.

Gesprov

• Requires the service monitoring API in the Gesprov installation.
• The unit that Gesprov blocks, releases and bills is the service; that is what appears as the contract on the card.
• Each synchronization goes through the entire service listing and completes phone numbers and email from the customer registry.
• Gesprov billing queries are made by the customer CPF/CNPJ, stored encrypted in the mirror and decrypted only at query time.
• Billing: open invoices, Pix from the gateway or from the bank slip (if the invoice has no Pix, ChatISP requests one from the gateway, which works with the Efí gateway), bank slip as PDF. The last payment only appears when Gesprov provides the settlement date.
• Trust unblocking by service; the rules (interval between unblocks, service already active) belong to Gesprov and a refusal comes back explained.

ReceitaNet

• Single-server system: the address comes pre-filled. Two credentials, either may be missing: the chat billing integration token and the Subscriber Portal Client ID and Client Secret.
• With the token, every charge already carries the customer record and the payment data (bank slip, digitable line and Pix copy and paste): the mirror is built from the charges themselves and billing reminders by due date query the API directly.
• With the Subscriber Portal: invoice copy with QR Code, paid invoices with the payment date and the trust unlock (payment notification). Without the Portal, the last payment does not appear and unlocking is not available.

Pipesoft

• Client ID and Client Secret of the API user (Provider > User Control > API). Grant that user the customer, plan and title controls; customer write access is only used by the trust unlock.
• The customer listing carries no phone or address: the full load queries each record individually, in parallel, and the following synchronizations redo the listing and complete the records in batches. On bases of a few thousand customers the first load takes a few minutes.
• Plan speed from the Pipesoft plan catalog (the number is the applied speed, with the provisioning margin). Without the plan control granted, the card shows only the plan name.
• Billing: all the customer titles, with the digitable line and Pix copy and paste; last payment; invoice copy; live lookup by CPF/CNPJ. The card Refresh button rereads the customer directly in Pipesoft.
• Trust unlock through the Pipesoft observation: the customer stops being blocked for late payment until the limit date (5 days by default) and the session is released.
• Billing reminders by due date through the ChatISP title mirror, renewed every 6 hours.

Capability comparison by ERP

Lookup by full name uses the local mirror, so it works for all of them; lookup by document queries the ERP live. How each feature appears to the agent is in Customer record: what depends on each ERP.

Local mirror and synchronization

To identify the customer by phone in milliseconds, without depending on the ERP answering at that moment, ChatISP keeps a lean copy of the subscribers of each active ERP: the local mirror.

What the mirror stores

One row per access (login or service) with the customer and contract codes in the ERP, connection login, name, plan, speed, normalized status, city, neighborhood, address, phone numbers and email. CPF/CNPJ, connection passwords and credentials that the ERP returns along with the data are discarded. The exception is Gesprov, whose document is stored encrypted because its API only handles billing by CPF/CNPJ.

When it synchronizes

In full loads, accesses that disappeared from the ERP change to Canceled in the mirror, instead of still showing as active.

Phone numbers

All phone fields of the registry go into the mirror, in the ERP order and without repeating the same number written in two ways. In the search, numbers are normalized with country code 55 and the ninth mobile digit. A number without an area code takes the area code of the neighboring number in the same field.

Import ERPs from Ravicor

With Ravicor connected through pairing, the Import from Ravicor button copies the ERPs registered in Ravicor into ChatISP, with address and credential. The notice {n} ERP(s) synced from Ravicor confirms it.

• Imported ERPs become ChatISP registrations of their own, marked as imported from Ravicor, with their own mirror.
• Importing again updates the address and credential of those already imported and creates the new ones. It never deletes anything: an ERP removed from Ravicor stays in ChatISP until it is deleted here.
• The Use this ERP in support checkbox is never changed by the import: the choice made in ChatISP prevails.
• If the ERP refuses the credential of an imported ERP (because it was changed in Ravicor), ChatISP reimports on its own and tries again.

External systems (generic API integration)

Any ISP system with an HTTP API (an in-house billing system, a CRM, a work order system) can be integrated without programming in ChatISP: you describe the operations in JSON and the AI, the flows and the customer card start using them. The JSON is the only list of allowed operations: only what is in it can be executed, always against the registered base address.

Register

1. In ERPs and external systems, click Add source and choose Other system.
2. Fill in the New system window (fields below).
3. Click Save. The JSON is validated immediately; a structure error appears as The operations JSON is not valid, followed by the problematic point.
4. Use Test in the table to run a real operation and see the response.

Operations format

{
  "operacoes": [
    {
      "id": "faturas_abertas",
      "descricao": "Lists the customer open invoices by CPF",
      "metodo": "GET",
      "caminho": "/api/v1/faturas?cpf={cpf}&situacao=aberta",
      "parametros": [{ "nome": "cpf", "descricao": "Customer CPF, digits only" }],
      "resposta": "list of invoices with due date, amount and bank slip link"
    },
    {
      "id": "liberar_confianca",
      "descricao": "Trust unblocking by customer code",
      "metodo": "POST",
      "caminho": "/api/v1/desbloqueio",
      "corpo": { "cliente": "{codigo}", "dias": 3 },
      "parametros": [{ "nome": "codigo", "descricao": "Customer code" }]
    }
  ]
}

ChatISP does not follow redirects and uses up to 64 KB of each response. Responses from 200 to 299 count as success.

The systems table

Columns Name (with the base address), Operations (how many), Available to the AI, Last test (date in green or red), Status and the actions Edit, Test and Delete (with the warning Delete this system? The AI and flows will stop using it.).

The test window lists the operations, opens a field for each parameter of the chosen operation and shows the response with the HTTP code. With no operations registered, Add operations to the JSON to test. appears.

Where operations are used

• AI: with Available to the AI on, the AI receives the list of operations with their descriptions and decides when to call each one. See Artificial intelligence.
• Flows: the Query system step chooses the system, the operation and the parameters, and answers the customer with {resposta.campo} in the message. With no system registered, the step shows Register an external system in Integrations to use this step. See Flows.
• Customer card: through the conventions in the next section.

External system conventions

Some customer record features are turned on automatically when the operations JSON declares parameters with agreed names. Just follow the names:

Responses wrapped in {"ok": true, "dados": {...}} are unwrapped automatically. When more than one operation fits, the one with fewer parameters is used. Manual linking to an external system only appears when the system declares both the search and the linked customer card.

ChatISP API (keys) Plan feature

The ChatISP API card ("Keys for other systems to use the API: messages, conversations, contacts, service orders, calendar and metrics, each key with its own permissions.") creates the keys that the ISP's ERP, CRM, subscriber portal, monitoring or BI use to work with customer service through the public API. The public API and webhooks are part of the plans from PREMIUM up; the number of active keys depends on the plan (3 on PREMIUM, 10 on GOLD, unlimited on ENTERPRISE). Outside the plan, the card shows the feature locked with the plan from which it is included. The meter next to the title shows how many keys are in use.

The top of the card shows the API address of your installation, with the hint the key goes in the Authorization: Bearer header, and the API documentation button, which opens the complete reference.

Create a key

1. Click New key.
2. Give it a Name that identifies the system that will use it. This name appears in the history of everything the key does.
3. Turn on only the permissions the integration needs (see the table below). On a new key, Send messages, Look up conversations and Open service requests come turned on.
4. With more than one WhatsApp number connected, choose the Sending number: the number this key sends from when the call does not name a connection. Without it, the API refuses any send that does not provide conexao_id. The option None (the call must name the connection) leaves the choice to each call. With a single number, the field is not shown.
5. Adjust the Per-minute limit: calls accepted per minute, default 60, maximum 10,000. 0 turns the limit off.
6. Click Save. The Key created window shows the full key with the Copy button.

Key permissions

The permissions are in three groups. Each one unlocks a set of API operations:

Connections, departments, agents, templates, tags and closing reasons are available to any active key, with no permission: they are the records every integration needs to build its calls. The technical code of each permission and the exact operations it unlocks are in Key permissions (scopes).

The keys table

• Columns Name, API key (only the beginning, for recognition), Permissions (one tag per permission turned on), Uses (hover to see Last use) and Status (Enabled or Disabled).
• Edit changes name, permissions and limit, and lets you disable the key without deleting it. The key itself does not change: the integration keeps the same value, now with the new permissions.
• Reveal shows the full key again, to those with the Integrations permission.
• Delete removes the key; the system that used it can no longer call the API.

The 37 operations, the call format, the error codes and the Postman and Insomnia collection are in the API documentation: Introduction to the ChatISP API.

Outgoing webhooks Plan feature

A webhook notifies one of your systems, over HTTP, when something happens in customer service. It is part of the same plan feature as the public API.

Create a webhook

1. Click New webhook.
2. Enter Name and Address (the URL that will receive the notifications).
3. Check the events (at least one). On a new webhook, Message received, Conversation created and Conversation closed come checked.
4. Click Save. The Webhook created window shows the Secret, used to verify the signature of each delivery.

Available events

How deliveries work

• Each event becomes a POST with a JSON body and the headers X-ChatISP-Evento, X-ChatISP-Entrega and X-ChatISP-Assinatura, which carries the HMAC SHA-256 of the body computed with the secret.
• Sending never delays customer service: the event enters a queue and is delivered in the background, usually a few seconds later.
• Responses from 200 to 299 count as delivered. The maximum wait for a response is 10 seconds.
• On failure, ChatISP tries again after 1 minute, 5 minutes, 15 minutes, 1 hour and 6 hours. After the last attempt, the delivery is discarded.

The webhooks table

Columns Name (with the URL), Events, Last delivery (hover to see the result; a highlighted number indicates deliveries in the queue) and Status. Actions: Edit (including disabling; pending deliveries are kept until you reactivate it), Test (delivers a test event immediately and reports Test delivery accepted or Test delivery failed, with the code or the error), Secret (reveals the secret) and Delete (pending deliveries are discarded).

The exact content of each event, signature verification in PHP, Node.js and Python, and the retry and duplicate rules are in Outgoing webhooks in the API documentation.

Google Calendar

Mirroring appointments to Google Calendar is individual: each user connects their own Google account in My account, on the Google Calendar card, with the Connect my Google account button. Authorization opens in a tab of the Ravi Systems connection hub; when it finishes, Google account connected. Your upcoming appointments will be mirrored. appears.

• It works in one direction only: appointments where the user is the person responsible appear in their Google calendar. What is created in Google does not come back to ChatISP.
• With the account connected, appointment types configured for it can create the Google Meet room automatically.
• Disconnecting keeps the events already created in Google; upcoming ones are no longer mirrored.

Details in Calendar.

System email

ChatISP sends few emails: invitations for new users and password recovery codes. These emails go out through a sending channel maintained by Ravi Systems, with no need to configure an SMTP server. There is no per-installation SMTP. Messages to the end customer always go out through WhatsApp.

Credential security

• Tokens, passwords and keys of ERPs, Ravicor and external systems are stored encrypted in the ChatISP database.
• ERP and external system credentials are write only: once saved, they never return to the screen. To change one, type the new value; leaving it blank keeps the current one.
• The Ravicor key obtained through pairing is not shown on any screen.
• ChatISP API keys and webhook secrets can be revealed again by those with the Integrations permission.
• Sensitive personal data that ERPs return (CPF/CNPJ, connection passwords) is discarded in the local mirror, except for the encrypted Gesprov and ReceitaNet document.
• External systems only run operations declared in the JSON and only against the registered base address.

Common problems