> For the complete documentation index, see [llms.txt](https://developer.gyfti.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gyfti.fr/hubspot-integration-v2/triggers-and-actions-reference.md).

# Triggers and Actions reference

### **Contact Resolution (How we identify the contact in HubSpot)**

For all triggers, Gyfti ensures that a contact exists in HubSpot before sending any event.

**General behavior**

* If a contact with the member's email already exists in HubSpot → we use that contact
* If no contact exists → we create a new one with that email

One person can be a member of several Gyfti espaces. They still have **one** HubSpot contact, so every event carries `instanceName` and `espaceSlug` to tell you which espace it came from.

> Nothing from a **sandbox** (test) espace, and nothing about a test contact, is ever sent to HubSpot.

***

#### Triggers

Every trigger is a HubSpot app event, so it shows on the contact's timeline and can enroll the contact in a workflow. Dates are sent as `DD/MM/YYYY HH:mm`, Paris time. A property with no value is left out.

**1. Espace joined (Gyfti v2)**

When a member creates their account in an espace.

**Data it sends:** `instanceName`, `espaceSlug`, `memberName`, `joinedAt`

***

**2. Espace signed in (Gyfti v2)**

Every time a member signs in to an espace.

**Data it sends:** `instanceName`, `espaceSlug`, `signedInAt`

***

**3. Challenge submitted (Gyfti v2)**

When a member sends their participation to a challenge. The event lands on the participant's own contact.

**Data it sends:** `instanceName`, `espaceSlug`, `challengeName`, `challengeId`, `participationId`, `participantName`, `submittedAt`, `allAnswers`, `answer1` to `answer10`

> `allAnswers` holds every answer. `answer1` to `answer10` hold the first ten, in the order the participant saw the questions: use them for branches in your workflow. A challenge with more than ten questions loses nothing, it is all in `allAnswers`.

***

**4. Challenge validated (Gyfti v2)**

When a submission is **approved**, in Gyfti or by the *Validate challenge submission (Gyfti v2)* action. A rejected submission, or one only opened for review, sends nothing.

**Data it sends:** `instanceName`, `espaceSlug`, `challengeName`, `challengeId`, `participationId`, `status`, `pointsAttributed`, `reviewedAt`

> `pointsAttributed` is a **number**, so you can sum it in a HubSpot report.

***

#### Actions

Actions are available inside contact-based HubSpot Workflows. Use them to trigger operations in Gyfti when a workflow condition is met.

Campaign, challenge, espace and segment are **dropdowns** loaded live from Gyfti. They only list what the workspaces connected to this HubSpot account can actually use.

Every action reports its real outcome: a success shows green in the workflow history, a failure shows red with a message saying why (see Troubleshooting below).

**Send a digital gyfti (Gyfti v2)**

What it does: Adds the contact to a digital gift campaign in Gyfti. Gyfti emails them so they can choose their gift.\
Required fields:

* `Campaign`: the digital campaign, picked from the list of launched campaigns
* `Email`: mapped from the contact's email property

Optional fields:

* `First name`, `Last name`, `Company`, `Phone`

Outputs: `Status`, `Campaign`, `Recipients added`

Example: Enroll a contact in a digital gift campaign when they reach the "Customer" lifecycle stage.

***

**Send a postal gyfti (Gyfti v2)**

What it does: Adds the contact to a postal campaign, with their shipping address. Gyfti ships the campaign's gift to that address.\
Required fields:

* All required fields from *Send a digital gyfti (Gyfti v2)*, plus:
* `Street address`, `Postal code`, `City`, `Country`

Optional fields:

* `First name`, `Last name`, `Company`, `Phone`, `Address complement`

Outputs: `Status`, `Campaign`, `Recipients added`

> A campaign whose product needs a **delivery appointment** is not listed: a workflow cannot choose that date. Send those campaigns from the Gyfti app.

Example: Send a physical gift when a deal is marked Closed Won, using the contact's shipping address.

***

**Validate challenge submission (Gyfti v2)**

What it does: Approves the contact's submission on a challenge and credits the challenge's points.\
Required fields:

* `Challenge`: picked from the list of active or paused challenges
* `Email`: mapped from the contact's email property, it names the participant

Outputs: `Status`, `Challenge`, `Points awarded`

Gyfti approves the contact's **oldest** submission still awaiting review on that challenge. If they have none, the action fails rather than doing nothing.

Example: Validate a submission automatically when a HubSpot form or deal confirms the challenge was done, and reward the member with the challenge's points.

***

**Edit a Gyfti user (Gyfti v2)**

What it does: Updates a member's name, segment or points balance in an espace.\
Required fields:

* `Espace`: the espace the member belongs to. One person can be a member of several espaces, so the email alone does not say which balance to change
* `Email`: identifies the member in that espace

Optional fields:

* `First name`, `Last name`: left unchanged if empty
* `Points`: **Add points** adds the value to the balance, **Set balance to** replaces the balance with it. Required as soon as `Points value` is filled
* `Points value`: a whole number
* `Segment`: one of the chosen espace's segments. A member is in one segment at a time
* `Or new segment`: a segment name to type instead. Gyfti reuses a segment of this espace with the same name (capitals, accents and spaces ignored) and creates it otherwise. Wins over `Segment`. 80 characters max
* `Send email`: **Yes** emails the member their new points balance, only when this action changed their points

Outputs: `Status`, `What changed`, `Points balance`, `Email to the member`, `Segment created`, `Segment used`

Example: Move a member to the "VIP" segment and add points when they hit a milestone.

***

#### Troubleshooting

**A dropdown is empty**

* **Campaign** lists the **launched** campaigns of a Touch workspace connected to this HubSpot account.
* **Challenge** lists the **active or paused** challenges of a connected Grow workspace.
* **Espace** lists the connected Engage and Grow espaces.
* **Segment** needs an espace first, then lists that espace's segments.

If a list stays empty, check in Gyfti that the workspace is connected to **this** HubSpot account (Réglages > Intégrations > Applications).

**Error messages**

| Message in the workflow history                                              | What to do                                                                                                      |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| The contact has no email address, so Gyfti cannot identify them.             | Add an "Email is known" filter to the workflow's enrollment.                                                    |
| Choose a campaign. / Choose a challenge. / Choose an espace.                 | A required dropdown is empty in the action.                                                                     |
| A postal gyfti needs a street, a postal code, a city and a country.          | One of the address properties is empty on the contact.                                                          |
| That challenge is no longer on a workspace linked to this HubSpot account.   | The challenge's workspace was unlinked. Reconnect it or pick another challenge.                                 |
| No member matches that id or email.                                          | The contact is not a member of the chosen espace. *Edit a Gyfti user* updates members, it does not create them. |
| That segment belongs to another espace. Pick a segment of the chosen espace. | The espace changed after the segment was picked. Pick the segment again.                                        |
| That segment no longer exists. Pick another one.                             | The segment was deleted in Gyfti.                                                                               |
| Choose « Add points » or « Set balance to » beside the amount.               | A points value is filled with no mode.                                                                          |
| The points value must be a whole number.                                     | Use a whole number.                                                                                             |
| This HubSpot portal is not connected to a Gyfti organization.                | No workspace is connected to this HubSpot account. See Setting up HubSpot.                                      |
| The Gyfti connection for this portal is inactive.                            | The HubSpot authorisation was revoked or expired. Reconnect the account in Gyfti.                               |

Other refusals (budget, stock, permissions) come back with their own message.

**Nothing reaches the timeline**

1. Check the workspace is connected (Réglages > Intégrations > Applications).
2. Check the event is turned on under « Ce qui remonte dans la timeline de vos contacts ».
3. Look at the recent activity on the same page: a skipped event says why, a failed one is retried automatically.
4. *Challenge validated* is only sent for an **approved** submission.
5. Nothing is sent from a sandbox espace.
