Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Last updated