Skip to content
Go to bejoyous.ai
  • There are no suggestions because the search field is empty.

Salesforce Joyous API Integration

Trigger a Joyous conversation from Salesforce via REST API

Trigger Joyous conversations from Salesforce using Flow HTTP Callout

This guide shows Salesforce admins how to trigger a Joyous conversation from Salesforce without installing a Joyous-managed app. It uses a standard Salesforce setup: Named Credentials, Flow HTTP Callout, and a Record-Triggered Flow. Joyous supports this pattern for any platform that can make an automated API call to an external system. (Joyous Help Centre)

What you’ll build

In this example, when a Salesforce record meets your chosen criteria, Salesforce sends a POST request to Joyous’s /events endpoint and Joyous sends a conversation by email. Joyous’s help article shows the same core request shape: orgId, location, recurringCampaignGroupId, email, sendConversation, and optional attributes. (Joyous Help Centre)

Before you start

You’ll need the following from Joyous:

  • your Joyous API Key

  • your Joyous orgId

  • your location

  • the recurringCampaignGroupId for the campaign you want to trigger

In Joyous, the campaign must be configured as an Event trigger campaign, and Joyous notes that your API key is copied from Settings → Integrations and can only be copied once, so store it securely. (Joyous Help Centre)

Example use case

This guide uses a simple example:

When a Case is closed, send a Joyous conversation to the Case Contact’s email address, and include two custom attributes:

  • caseNumber

  • priority

You can adapt the same pattern for Leads, Contacts, Opportunities, custom objects, or any other Salesforce process.

Step 1: Set up the Joyous campaign

In Joyous:

  1. Create or open the campaign you want Salesforce to trigger.

  2. In the campaign timing settings, set the lifecycle to Event trigger.

  3. Copy the campaign’s request template details, especially the recurringCampaignGroupId.

  4. Copy your API key from Settings → Integrations. (Joyous Help Centre)

Step 2: Create the authentication in Salesforce

Salesforce’s current model is to use an External Credential for authentication and a Named Credential for the endpoint URL. Salesforce documents that a named credential defines the callout endpoint and transport, while the external credential handles authentication and can be reused across named credentials. (Developer)

Create the External Credential

In Salesforce Setup:

  1. Search for Named Credentials.

  2. Open Named Credentials.

  3. Go to the External Credentials tab.

  4. Click New.

  5. Create an external credential for Joyous.

Use a setup that sends the API key in a custom header named x-api-key. Salesforce supports custom headers for named credential-based callouts, including API-key style authentication. (Developer)

Create the Named Credential

Still in Named Credentials:

  1. Go to the Named Credentials tab.

  2. Click New.

  3. Create a named credential such as Joyous_API.

  4. Set the base URL to:

https://eta1.joyoushq.com

  1. Link it to your Joyous external credential.

Joyous’s own example uses:

  • base URL https://eta1.joyoushq.com

  • resource path /events

  • header x-api-key. (Joyous Help Centre)

Grant access to the external credential principal

Salesforce notes that external credential principals map to user permissions, so make sure the user who will run the flow has access to the external credential principal. (Developer)

Step 3: Create the HTTP Callout action in Flow

Salesforce Flow can call external APIs by using Flow HTTP Callout with a Named Credential. (Developer)

In Setup:

  1. Go to Flows.

  2. Create a new Flow or open the one you want to use.

  3. Add an Action.

  4. Create an HTTP Callout action.

  5. Select your named credential, for example Joyous_API.

  6. Configure the request as:

    • Method: POST

    • Path: /events

For the request body, use a sample JSON structure like this:

{
  "orgId": "YOUR_JOYOUS_ORG_ID",
  "location": "US",
  "recurringCampaignGroupId": "YOUR_CAMPAIGN_ID",
  "email": "sample@example.com",
  "sendConversation": true,
  "attributes": [
    {
      "name": "caseNumber",
      "value": "00012345"
    },
    {
      "name": "priority",
      "value": "High"
    }
  ]
}

This matches Joyous’s documented event trigger request pattern, including optional custom attributes. (Joyous Help Centre)

Step 4: Build the Record-Triggered Flow

Now build the Salesforce automation that decides when to call Joyous.

For example:

  1. Create a Record-Triggered Flow

  2. Object: Case

  3. Trigger: When a record is updated

  4. Condition: Status = Closed

Then add your Joyous HTTP Callout action and map the request fields.

Example field mapping

Use values like:

  • orgId → your Joyous org ID

  • location → your Joyous location, for example US

  • recurringCampaignGroupId → the campaign ID from Joyous

  • email → Case.Contact.Email

  • sendConversation → true

  • attributes[0].name → caseNumber

  • attributes[0].value → Case.CaseNumber

  • attributes[1].name → priority

  • attributes[1].value → Case.Priority

Joyous’s help article shows the same pattern: pass the campaign ID, the contact field such as email, and optionally an attributes array for filtering and reporting. (Joyous Help Centre)

Example final request

A real request sent from Salesforce could look like this:

{
  "orgId": "1dMGXaiV8u1Bb3N_",
  "location": "US",
  "recurringCampaignGroupId": "7WtSbc7sQkHGuBGa",
  "email": "customer@example.com",
  "sendConversation": true,
  "attributes": [
    {
      "name": "caseNumber",
      "value": "00012345"
    },
    {
      "name": "priority",
      "value": "High"
    }
  ]
}

Optional variations

Send by SMS instead of email

Joyous notes that for SMS-based triggering, replace email with mobilePhone. If you want both email and SMS in different scenarios, Joyous recommends creating separate actions/configurations. (Joyous Help Centre)

Include a reference

Joyous also supports passing a reference field so the recipient knows what the feedback request relates to. The token can then be used in the Joyous campaign. (Joyous Help Centre)

Add more custom attributes

Joyous supports additional key/value custom attributes in the attributes array, which can then be used for filtering in Joyous. (Joyous Help Centre)

Testing tips

  • Test first in a Salesforce sandbox if possible.

  • Trigger the flow with a real record update, not just a design-time check.

  • Confirm that the flow user has access to the Joyous external credential principal.

  • Confirm that the Joyous campaign is configured as an Event trigger campaign.

  • Double-check the recurringCampaignGroupId, orgId, and location values if requests are not behaving as expected. Joyous’s guide highlights these as required parts of the request. (Joyous Help Centre)

Summary

To manually trigger Joyous conversations from Salesforce:

  1. Create an Event trigger campaign in Joyous and copy the API details. (Joyous Help Centre)

  2. Create an External Credential and Named Credential in Salesforce for Joyous. (Developer)

  3. Build a Flow HTTP Callout to POST /events. (Joyous Help Centre)

  4. Use a Record-Triggered Flow to map Salesforce record values into the Joyous request body.

  5. Test with a real record change.

This gives you a flexible, app-free way to trigger Joyous from Salesforce using standard admin tools.