> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/getting-started-with-advocate/import-your-referral-program-data.md).

# Importa i dati del tuo programma di referral

Quando passi da un’altra piattaforma di referral ad Advocate, non ti limiti a importare i dati: potenzi le possibilità del tuo programma grazie a un monitoraggio efficace, esperienze personalizzabili e supporto esperto. In questo articolo vedrai:

* Perché la migrazione è importante
* Come si presenta un piano strategico di migrazione
* Quali dati si possono importare
* Come preparare i file
* Errori di convalida comuni e come evitarli

#### Perché pianificare una migrazione strategica?

La migrazione del tuo programma di referral non è solo un’attività tecnica: è un’occasione per migliorare il modo in cui coinvolgi e premi i clienti. Una migrazione pianificata con cura ti aiuta a:

* Ridurre al minimo le interruzioni dell’esperienza di referral
* Conservare i dati storici e garantire la continuità dei premi ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media)
* Abbandonare senza problemi i sistemi precedenti
* Rilanciare il programma di referral con entusiasmo e chiarezza

![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) La migrazione dei referral e dei premi dipende dalla possibilità di esportare i dati dal sistema attuale. Il team Advocate potrà indicarti cosa è possibile fare in base ai dati esportati che fornisci.

Il team Advocate collaborerà con te per esaminare i file esportati, individuare ciò che è fattibile e creare un piano in linea con le esigenze e gli obiettivi del tuo programma.

#### Cosa dovrai fare

* Esporta i dati del programma relativi a *utenti*, *referral* e  *premi*. Per ricevere assistenza, contatta il tuo CSM sulla piattaforma di referral precedente oppure usa uno strumento di esportazione integrato, se disponibile.
* Scarica i 3 report di dati, ciascuno in un file CSV separato, ad esempio: `user_data.CSV`, `referral_data.CSV` e  `reward_data.CSV`.
  * Consulta gli esempi qui sotto per vedere come potrebbero essere i contenuti di ciascun file .csv oppure consulta la documentazione completa dei campi di destinazione.

Include email, codici referral e link di condivisione ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media), oltre ai campi personalizzati. Gli affiliati devono essere esclusi per evitare doppi premi.

![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) Dipende dal formato del link di condivisione e dall’uso di un sottodominio personalizzato.

Il file User Data conterrà informazioni dettagliate su ogni partecipante al programma. Esporta un elenco di tutti i partecipanti per mantenere aggiornati i link di condivisione e i codici referral del programma.

I seguenti campi sono **obbligatori**:

* ID utente
* ID account

Usa l’indirizzo email dell’utente come *ID utente*  e  *ID account*. Le date devono essere espresse in [millisecondi dall’epoca Unix](https://currentmillis.com/). Scarica un [esempio dei campi obbligatori](https://res.cloudinary.com/product-enablement/raw/upload/v1750169976/CSVs/Migration_User_Import_examples_-_User_Data.csv) oppure usa l’esempio qui sotto nel formato `.csv` .

```programlisting
id,accountId,email,firstName,lastName,dateCreated,locale,countryCode,segments
User1@example.com,User1@example.com,User1@example.com,First,Last,1741051242000,en_US,US,
User2@example.com,User2@example.com,User2@example.com,First,Last,,,,"vip,newuser"
User3@example.com,User3@example.com,User3@example.com,First,Last,,en_CA,,
User4@example.com,User4@example.com,User4@example.com,First,Last,,,,newuser
```

Include date di inizio e conversione, nonché le relazioni tra chi invita e chi viene invitato. Consente di mappare le prestazioni storiche delle segnalazioni.

Il file dei dati delle segnalazioni contiene un record dello stato di ogni collegamento tra segnalazioni creato nel programma di referral.

I seguenti campi sono **obbligatori**:

* ID utente di chi invita
* ID account di chi invita
* ID utente di chi viene invitato
* ID account di chi viene invitato

Usa l’indirizzo email dell’utente come *ID utente*  e  *ID account*. Le date devono essere espresse in [millisecondi dall’epoca Unix](https://currentmillis.com/). Scarica un [esempio dei campi obbligatori](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Referral_Data_-_Referral_Data.csv) oppure usa l’esempio qui sotto nel formato `.csv` .

```programlisting
referrerUser,referrerAccount,referredUser,referredAccount,dateReferralStarted,dateConverted,programId
User2@example.com,User2@example.com,User12@example.com,User12@example.com,1740824979000,1740824979000,33435
User1@example.com,User1@example.com,User13@example.com,User13@example.com,1741051242000,1741051242000,33435
User1@example.com,User1@example.com,User17@example.com,User17@example.com,,,33435
User1@example.com,User1@example.com,User18@example.com,User18@example.com,,,33435
```

Include valori, date di assegnazione e riscatto, tipi di premio e stati. Consente di preservare credibilità ed equità nei confronti degli utenti.

Il file dei dati dei premi contiene un registro dello storico dei premi dei partecipanti, compresi il loro valore e l’importo riscattato tramite il programma di referral.

I seguenti campi sono **obbligatori**:

* ID utente di chi invita
* ID account di chi invita
* Nome del premio
* Unità del premio
* Valore del premio
* Data di creazione
* Data di assegnazione
* Data di riscatto
* Importo riscattato

Usa l’indirizzo email dell’utente come *ID utente* e *ID account*. Le date devono essere formattate in [millisecondi dall’epoca Unix](https://currentmillis.com/).

Il valore del premio è il valore numerico del premio espresso nella sua unità di misura più piccola (ad esempio, per un premio in denaro di 1,00 $, il valore sarebbe 100 centesimi). Se l’unità del premio è una valuta, deve includere il codice della valuta nel formato seguente `<unitName>/<Currency>` (ad es., Cash/USD).

{% hint style="warning" %}
**Importante**: se i campi *Data di riscatto* e *Importo riscattato* non sono impostati correttamente, ovvero vengono lasciati vuoti o contengono valori errati (ad esempio, una data futura o un importo riscattato inesatto), l’utente potrebbe poter riscattare nuovamente il premio.
{% endhint %}

Scarica un [esempio dei campi richiesti](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Reward_Data_-_Reward_Data.csv) oppure usa l’esempio qui sotto in formato `.csv` .

```programlisting
ID utente,ID account,ID utente invitato,ID account invitato,Nome del premio,Unità del premio,Valore del premio,Importo riscattato,Data di creazione,Data di assegnazione,Data di riscatto
User1@example.com,User1@example.com,User2@example.com,User2@example.com,Dollars,CASH/USD,1000,1000,1709712158000,1709712158000,1709712158000
User1@example.com,User1@example.com,User3@example.com,User3@example.com,Points,POINT,100,100,1726164909682,1726164909682,1726164909682
User1@example.com,User1@example.com,User4@example.com,User4@example.com,Points,POINT,100,100,1726164887075,1726164887075,1726164887075
User1@example.com,User1@example.com,User5@example.com,User5@example.com,Points,POINT,100,100,1726164875888,1726164875888,1726164875888
User1@example.com,User1@example.com,User6@example.com,User6@example.com,Points,POINT,10,10,1726164828986,1726164828986,1726164828986
User1@example.com,User1@example.com,User7@example.com,User7@example.com,Account Credit,USD,8000,8000,1726164289997,1726164289997,1726164289997
User1@example.com,User1@example.com,,,Gift Card,USD,10000,10000,1726163864871,1726163864871,1726163864871
User1@example.com,User1@example.com,,,Points,POINT,800,800,1726095906392,1726095906392,1726095906392
User1@example.com,User1@example.com,,,Gift Card,USD,30000,30000,1726163769157,1726163769157,1726163769157
User1@example.com,User1@example.com,,,20 Off,%,20,20,1726180309034,1726180309034,1726180309034
```

{% hint style="warning" %}
**Importante:** Tutti e 3 i file di esportazione devono contenere dati di un solo programma. Se i file contengono dati di più programmi, l'importazione li consoliderà in un unico programma.
{% endhint %}

<details>

<summary>Un esempio di piano di migrazione</summary>

Ogni migrazione è diversa, ma quelle riuscite seguono una struttura simile che bilancia preparazione, comunicazione ed esecuzione. Di seguito è riportato un piano di migrazione che garantisce continuità e un'esperienza senza intoppi sia per il tuo team sia per i tuoi ambassador. Le tempistiche e le fasi possono variare a seconda della configurazione del programma.

**Fase 1: Pianificazione e preparazione (1–2 settimane)**

Questa è la fase in cui si pongono le basi per una transizione senza intoppi.

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Obiettivi    | <p>• Allineare le parti interessate.</p><p>• Configurazione tecnica.</p><p>• Confermare l'ambito della migrazione.</p><p>• Pianificare la comunicazione agli utenti.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Attività     | <p>• Preparare un campione dei dati storici (utenti, referral, premi) e condividerlo con il team Advocate per la revisione e la mappatura dei campi <img src="https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media" alt="">.</p><p>• Esportare tutti i set di dati una volta convalidato il campione. È probabile che i dati esportati debbano essere modificati (ad esempio, aggiornando le intestazioni, i nomi dei campi o la struttura dei file) per soddisfare i requisiti di importazione.</p><p>• Stabilire una data di attivazione e una finestra per il ripristino.</p><p>• Aggiungere i widget Advocate in modalità nascosta (ambiente di test o pagine non collegate).</p><p>• Configurare le integrazioni necessarie (ad esempio, Shopify, HubSpot, Segment).</p><p>• Completare la configurazione del programma in Advocate (ad esempio, impostazione dei premi, regole del programma, modelli email, segmentazione).</p><p>• Testare il funzionamento del programma dall'inizio alla fine: verificare che le condivisioni, le conversioni e i premi vengano tracciati correttamente in un ambiente di test prima dell'attivazione.</p><p>• Preparare i messaggi per comunicare la transizione agli ambassador.</p><p><img src="https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media" alt=""> La migrazione dei referral e dei premi dipende dalla possibilità di esportare i dati dal sistema attuale. Il team Advocate può indicarti cosa è possibile fare in base ai dati di esportazione che fornisci.</p> |
| Suggerimenti | <p>• Se usi contemporaneamente più piattaforme, assicurati che solo una distribuisca i premi.</p><p>• Individua gli utenti più attivi che potrebbero richiedere un trattamento speciale (VIP, influencer).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

**Fase 2: Passaggio e attivazione (1-2 giorni)**

È il momento della transizione. Prevedi una breve pausa nel tracciamento tra i due sistemi e, se possibile, pianificala nelle ore di minor traffico.

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Obiettivi    | <p>• Passare senza interruzioni dalla piattaforma precedente ad Advocate.</p><p>• Assicurarsi che gli utenti possano accedere subito alla nuova esperienza.</p><p>• Evitare la perdita di dati sui referral o sui premi.</p>                                                                                                                                                                                                                                                                                                                                                                                                  |
| Attività     | <p>• Rimuovere dal sito gli script e i widget della vecchia piattaforma.</p><p>• Attivare i widget Advocate.</p><p>• Importare i dati definitivi di utenti, referral e premi.</p><p>• Monitorare manualmente e segnalare eventuali conversioni avvenute tra la chiusura del vecchio sistema e l'avvio del nuovo.</p><p>• Monitorare le attività nella dashboard di Advocate.</p><p>• Inviare agli ambassador una comunicazione di lancio. Informare gli utenti che i link di referral sono stati aggiornati e, idealmente, includere direttamente nella email i nuovi link, così potranno iniziare subito a condividerli.</p> |
| Suggerimenti | <p>• Se necessario, prevedere un breve periodo di sospensione dei premi (ad esempio: “I referral effettuati il 15 maggio saranno verificati e aggiunti dopo il lancio.”).</p><p>• Usare comunicazioni rivolte agli ambassador per creare entusiasmo (ad esempio: “Abbiamo migliorato la tua esperienza di referral!”).</p>                                                                                                                                                                                                                                                                                                    |

**Fase 3: Dopo la migrazione e operazioni di pulizia (1–2 giorni)**

Ora che il programma è attivo, assicurati che funzioni come previsto e risolvi eventuali questioni in sospeso.

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Obiettivi    | <p>• Verificare l'integrità dei dati e il tracciamento dei premi.</p><p>• Registrare eventuali conversioni non rilevate.</p><p>• Fornire assistenza e informazioni agli utenti.</p>                                                                                                                                                                                                                                                                                                                                                                       |
| Attività     | <p>• Verificare che le relazioni tra chi segnala e l'utente segnalato funzionino nella modalità attiva.</p><p>• Importare eventuali conversioni non rilevate avvenute durante il passaggio.</p><p>• Eseguire un test di controllo qualità (effettuare un referral a sé stessi e verificare il tracciamento e la logica dei premi).</p><p>• Fornire FAQ o documenti di assistenza per il team interno e gli utenti.</p><p>• Monitorare la casella di posta dell'assistenza per individuare problemi relativi agli utenti della piattaforma precedente.</p> |
| Suggerimenti | <p>• Se stai dismettendo un account di finanziamento dei premi della piattaforma precedente, concedi agli utenti un periodo di tolleranza per riscattarli.</p><p>• Usare email o promemoria nell'app per incentivare le prime attività di referral nel nuovo programma.</p>                                                                                                                                                                                                                                                                               |

</details>

#### Importa i dati del tuo programma

1. Nel menu di navigazione a sinistra, seleziona ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage] → Reporting → Imports & Exports**.
2. Nell'angolo in alto a destra, seleziona ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-ec3276f07285180fbb2167a40e148d3e43e8681c%2F05aa88f72076df5a744d4620574f19cc187b7154fe1f3bb73ad7a892b7d23002.svg?alt=media) **Importa**.
3. Seleziona *Tipo di importazione* tra le opzioni disponibili:

   | Tipo di importazione                    | Descrizione                                                                                                                                                                                                                                                      |
   | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Utenti                                  | Seleziona questa opzione per caricare nuovi utenti o i dati di utenti esistenti. Puoi anche scegliere di importare questi dati da un altro account o piattaforma.                                                                                                |
   | Aggiorna i saldi dei premi degli utenti | Seleziona questa opzione per aggiornare e riscattare i saldi dei premi degli utenti.                                                                                                                                                                             |
   | Eventi utente                           | Seleziona questa opzione per caricare i dati degli eventi utente.                                                                                                                                                                                                |
   | Elimina utenti                          | <p>Seleziona questa opzione se vuoi eliminare in blocco gli utenti esistenti dal tuo programma.</p><p>Puoi anche eliminare gli utenti e scegliere di:</p><p>• Conservare gli account vuoti</p><p>• Impedire che gli utenti eliminati vengano creati di nuovo</p> |
   | Cronologia dei premi                    | Seleziona questa opzione per caricare un registro di tutte le informazioni sui premi. Puoi anche scegliere di importare questi dati da un altro account o piattaforma.                                                                                           |
   | Cronologia dei referral                 | Seleziona questa opzione per caricare un registro di tutte le connessioni di referral. Puoi anche scegliere di importare questi dati da un altro account o piattaforma.                                                                                          |
4. Seleziona **Scegli file** oppure trascina e rilascia il file da importare.
5. Seleziona **Importa** per caricare i tuoi dati.
   * Se elimini in blocco gli utenti esistenti, seleziona **Eliminazione in blocco**.

#### Riferimento agli errori di convalida

Puoi riscontrare 3 tipi di errori di convalida:

1. **Messaggio di errore in linea:** vengono visualizzati nella tabella di convalida dell'anteprima e le righe con errori vengono evidenziate in rosso:

   * `INVALID_FIELD` — ad es., il campo *Data di creazione* non era nel formato [millisecondi dall'epoca Unix](https://currentmillis.com/) .
   * `MISSING_FIELD` — ad es., manca un campo obbligatorio come *ID utente* oppure *ID account* .

   <div data-with-frame="true"><figure><img src="https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-eb521fbbc452c243d6b3763ebcb90053b4e9e4dc%2Ff969fa535707c24f4913282d07287a546b348f2448bdb4ca2eef0a30c871fbb6.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>
2. **Avviso di errore:** vengono visualizzati al posto della tabella di convalida dell'anteprima, come messaggi di avviso rossi:

   * `MISSING_HEADER` — ad es., manca un'intestazione di colonna obbligatoria come *ID account* oppure *Valore del premio* manca.
   * `CSV_PARSING` — ad esempio, il file CSV contiene caratteri speciali con una formattazione non corretta.
   * `FILE_REF_IO` — ad esempio, il file è danneggiato e non può essere letto.

   <div data-with-frame="true"><figure><img src="https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FqSd1JDFy8AQDR2aGJdrz%2FScreenshot%202026-05-25%20at%2017.58.06.png?alt=media&amp;token=26f43eaf-904a-4e1f-8b3c-185700af5edc" alt="" width="563"><figcaption></figcaption></figure></div>
3. **Errori elencati:** vengono visualizzati come elenco del numero di errori nella schermata *Importazioni ed esportazioni* nella sezione *Report* quando il tipo di importazione non dispone di una tabella di convalida dell’anteprima. Gli errori di riga e di file vengono visualizzati insieme:

   <div data-with-frame="true"><figure><img src="https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FQuMoDG2ppJmsEdDwdw50%2FUntitled%20design%20(48).png?alt=media&amp;token=b1cbcb03-ffc7-4ad7-bbbd-c54b81ee3638" alt="" width="563"><figcaption></figcaption></figure></div>

#### Assistenza

Non devi affrontare la migrazione da solo. Il nostro team di onboarding Advocate è pronto ad aiutarti con:

* Supporto per la mappatura dei campi
* Indicazioni sulla formattazione dei dati
* Strategia di migrazione dei premi
* Test e controllo qualità

Contatta il [team di assistenza Advocate](mailto:support-advocate@impact.com).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/getting-started-with-advocate/import-your-referral-program-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
