> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sperant connector

> Connect Sperant, the real estate CRM, to woku and survey every client after their visit to a project, ordered by seller and sales team

The **woku Sperant connector** turns every **visit registered in Sperant** into a woku review of
the seller's advice. woku invites the client by **WhatsApp or email**, files the reviews in folders
by **sales team** and **seller**, and sets up **support tickets** and **action plans** per team. It
changes nothing in your Sperant account: it only reads the sellers, projects and clients it needs
to create each review.

## What a visit is

Sperant notifies woku of **every** event it has, but only two count as a visit:

| Sperant event | Counts as a visit when |
| - | - |
| **New client** (`client_created`) | Its input channel is one of the configured ones (by default **Visita Presencial**) |
| **Manual activity** (`activity_manual_created`) | Its interaction type is one of the configured ones (by default **Visita al proyecto** and **Visita a oficinas**) |

The values are compared ignoring case and accents, and you edit them in the integration's
**Visits** section. Any other event is received and ignored.

## How it works

1. A seller registers a visit to a project in Sperant (a new client who walks in, or a visit
   activity).
2. Sperant notifies woku. woku reads the **seller** name, the **project** and, for an activity,
   the **client's** phone and email from Sperant.
3. woku creates a review with the text **"Asesoría brindada por (seller) en el proyecto
   (project)"** (or its English version) and the **seller's photo**, inside the seller's folder,
   which sits inside their team's folder.
4. woku invites the client right away: by **WhatsApp** if they have a valid phone, or by
   **email** if not. With no phone or email, the review is still created, but nothing is sent.
5. The answer arrives like any other review and feeds your metrics, the support tickets and the
   action plans of its team.

Each visit is processed **only once**: if Sperant retries the same notice, woku does not create a
second review or send a second invitation.

## How to connect

**1. Paste your Sperant API key**

In **Company → Integrations → Sperant**, paste your Sperant account **API key**, choose the
invitation language and click **Connect**. woku validates the key against Sperant before
saving it.

**2. Set up the webhook in Sperant**

Once connected, woku shows you the webhook **token** **only once**, together with the URL
`https://api.woku.app/integrations/sperant/webhooks`. Set up your Sperant account's webhook
with that URL and token: Sperant sends the token with every notice, which tells woku the notice
is yours.

**3. Order your teams and sellers**

Create your **sales teams** and assign each seller to their team (see below). Sellers show up
on their own with their first visit, or you can pull them all at once with **Pull sellers from
Sperant**.

> [!WARNING]
>
> The token is shown **only once**. If you lose it, click **Generate a new token** in the Connection
> section: the previous one stops working right away, so update it in Sperant too.

## Teams and sellers

### Teams

In the **Teams** section you create, rename, order and remove your sales teams. Each team has:

* its **folder**, which holds its sellers' folders;
* its **action plan group**, which drafts a plan every **30 new improvement opportunities** from
  that team;
* optionally, its own **support destination**: if you add emails to the team, the tickets from
  that team's reviews go to those emails instead of the integration's general destination.

Removing a team **disables** its group and destination (it does not delete them) and leaves its
sellers **without a team**.

### Sellers

In the **Sellers** section you see each seller with their photo, their Sperant role and their last
visit. There you assign them a **team** and upload a **photo**, which is the image of their
reviews (without one, the moment's image or your company logo is used). The **Unassigned** filter
shows the sellers without a team.

A new seller who has no team yet **does not lose their visits**: their reviews are created in the
**Sin equipo** (no team) folder. When you assign them a team, their folder moves under the team's
folder and their reviews, **past and future**, count for that team in action plans and support
tickets. That move runs in the background and takes a few minutes.

## Folder organization

```
📁 North team            (team folder)
├── 📁 Ana Pérez         (reviews of her visits)
└── 📁 Luis Rojas
📁 Sin equipo
└── 📁 New seller
```

## The journey

In **Visit journey** you see the **Visit** moment: the review sent as soon as Sperant registers the
visit. You can turn it off, choose the **channel** (WhatsApp then email, or email only), write your
own **message** in Spanish and English (use `{seller}` and `{project}` to include the seller and
the project) and upload an **image** for sellers without a photo.

> [!NOTE]
>
> The journey definition is **yours**: once you save your changes, woku stops overwriting it with the
> defaults.

## Support tickets and action plans

When you connect Sperant, woku creates **once** two resources named **Integración Sperant**:

| Resource | What it does |
| - | - |
| **Support destination** (email) | Receives the [support tickets](https://woku.app/docs/en/guides/support-tickets.md) of the reviews that need attention, when their team has no emails of its own. They go to the email of the person who connected Sperant. |
| **Action plan group** | Listens to the reviews of every team and, when it gathers **100 new improvement opportunities**, drafts an [action plan](https://woku.app/docs/en/action-plans/create-plan.md). |

Each **team** also adds its own action plan group (30 improvements) and, if you give it emails, its
own support destination, which takes priority over the integration's.

> [!NOTE]
>
> The destinations and groups are **yours**: you can edit them (add emails or owners, change the
> threshold), disable them or delete them from **Support** and **Action plans**. woku only updates
> the name of a team you rename and the emails you edit in the Teams section, and disables those of a
> team you remove.

## What data woku uses

* **From the Sperant notice**: the event type, the seller, the project, the input channel or the
  interaction type, and the new client's phone and email.
* **From the Sperant API**: the seller's name, the project's name and, for an activity, the
  client's phone and email.

Every review is tagged with the trackers `sperant_seller_id`, `sperant_team`,
`sperant_project_id`, `sperant_project_name` and `sperant_event`, so you can filter and group your
results by seller, team and project.

## FAQ

> **What happens to the Sperant events that are not visits?**
>
> woku receives them and answers right away, but creates nothing. This way Sperant never sees an
> error from woku.

> **How do I test the integration without contacting clients?**
>
> Turn on **Test mode** in Settings: visits still create their reviews, but no invitation is
> sent. The **Status** section shows the last event received and the last visit registered.

> **What happens if I change the API key in Sperant?**
>
> Paste the new key in the integration's **API key** section. If Sperant rejects the stored key,
> woku says so in the Status section and stops registering visits until you update it.

> **How do I disconnect Sperant?**
>
> In **Company → Integrations → Sperant → Disconnect**. The connection and its credentials are
> removed; the reviews, answers, groups and destinations already created **are kept**. Remember
> to remove the webhook in Sperant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.