Avochato for Salesforce Quickstart

Installation guide

Preview

Estimated setup time: 15 minutes

Welcome to Avochato for Salesforce! Follow the instructions below to get started!

🤔
In order to properly configure Avochato for Salesforce, make sure a user with the System Administrator profile carries out the following instructions

I. 🎬 Login & Install


  • A. Login to your Avochato account, or sign up for a free trial at www.avochato.com/signin
    • Being logged into www.avochato.com from the start will help with a smooth installation and authentication.
  • C. Enabled the Avochato API sync
    • With the Avochato platform, to integrate leads, contacts, and SMS activity into Salesforce, click on Integrations icon in the left sidebar and then click on the "Add Production" button.
    • Once authentication is successful, all interactions in Avochato will post as tasks on the corresponding lead or contact in Salesforce. New leads/contacts will come over into Salesforce automatically when new conversations happen in Avochato.

II. 👷‍♂️ Apply Licenses & Permission Sets


In order to setup all licenses and permissions sets, you can use one of the two following options:

1. Simple Setup via the Avochato Setup Tab


Use the Avochato Setup tab within Salesforce to do all the setup items in this section! The setup page also shows you the current status of your licenses, permissions, and connected apps.

Type in Avochato Setup within the App Launcher (3 by 3 dots icon in the left side of the Salesforce header) to access the setup page and follow the steps on screen. NOTE: The Avochato Setup tab only works for Salesforce Lightning. Salesforce Classic users can still use the manual steps specified in Section II.2 below.

Click into the follow page below for step by step guidance through the Avochato Setup tab

2. Manual Setup via the Salesforce Setup UI


Assign licenses and permission sets to your users (according to the number of licenses you purchased) will give them the proper access to the Avochato for Salesforce components.

⚠️
NOTE: If you did not apply these licenses and/or permission sets correctly to the right users, Avochato for Salesforce will not work as expected.
  • A. Apply Avochato for Salesforce Licenses
    ℹ️
    Applying licenses only applies to an active subscription in the Production org. The initial trial and any Sandbox org will give you unlimited licenses by default (although you still need to apply the Permission Sets coming up below)
    1. Go into Setup and type "Installed Packages" in the Quick find and click Installed Packages
    1. In the list of installed packages, click on the Manage Licenses link to the left of the Avochato for Salesforce package
    1. Within the Manage Licenses page, you'll see an overview of how many licenses you have, and who has licenses assigned to them. Click on the "Add Users" button to start adding users
    1. From the Available Users section, check off the users you'd like to give licenses to, and click the "Add" button at the bottom of the page
    1. Those users now have Avochato for Salesforce licenses activated for their Salesforce login
  • B. Apply Basic Permission Set
    1. Go to Setup and type “Permission Sets” in the Quick find, and click Permission Sets
    1. Click on the “Avochato User” permission set
    1. Click on the “Manage Assignments” button
    1. Click on the “Add Assignments” button
    1. From the list of users, check off all the users you’d like to have access to the Avochato for Salesforce component and click “Assign”
  • C. Create and Apply Connected App Permission Set
    1. Go to Setup and type “Permission Sets” in the Quick find, and click Permission Sets
    1. Click on the “New” button
      1. Set the label to “Avochato Connected App User”
        1. NOTE: The API Name should autopopulate
        1. Optional - set description to “To give access to Avochato Connected Apps”
      1. Set the License to “Salesforce”
      1. Click “Save”
    1. Click on the “Assigned Connected Apps” link within the “Apps” section of the Permission Set
      1. Click the “Edit” button on the next screen
      1. Select “Avochato for Salesforce” and move it over to the Enabled Connected Apps section. Move "Avochato API" into this section as well
      1. Click “Save”
    1. Click the “Manage Assignments” button, then click the “Add Assignments” button
      1. Select all the users that you’d like to use Avochato for Salesforce, and then click “Assign”
    1. Done! Should see a confirmation page that the assignment was made correctly.
  • D. Adjust Connected App Settings
    1. Go into Setup → Apps → Connected Apps → Manage Connected Apps
    1. Click on the Edit link next to Avochato for Salesforce
    1. Under the OAuth policies section, ensure that "Admin approved users are pre-authorized" option is selected. Your Avochato components will not work correctly without this setting
    1. Under the OAuth policies section, adjust the IP Relaxation settings to "Enforce IP restrictions, but relax for refresh tokens"
    1. If you have already enabled the Avochato API sync as specified in section I.C above (or plan to enable it), repeat the previous step above (Step 4 only) for the Avochato API connected app. This applies the same IP Relaxation settings as you did for the Avochato for Salesforce connected app, and ensures uninterrupted activity syncing between the Avochato Platform and your Salesforce org.

III. 🖥 Embed within Salesforce


Follow the instructions below to put the Avochato component directly into your Salesforce page

👉
In order to use the Avochato component within the Lightning Experience, please ensure "My Domain" is enabled for your Salesforce org. See section VI.E. below for setup instructions.
  • A. Add Avochato for Salesforce to any Standard or Custom Object Record Pages

    In Lightning:

    1. Navigate to a record page (in our examples, we'd choose a Lead record), click the Setup gear icon in the upper right corner of the page, and click “Edit Page”
    1. Within the Lightning App Builder, scroll down on the left sidebar into the Custom - Managed components section until you see the Avochato component (or type "avochato" into the Quick Find box)
    1. Drag the Avochato component into the desired space on the Lightning Page.
    1. (Optional) Adjust the “Height” value (in pixels) to the desired component height. Leave blank to use the Avochato default height
    1. Set the Component Type to “RecordPage”
    1. Click "Save" and Avochato should be embedded into your Contact lightning page
      🤔
      If this is your first lightning page that you're editing on the current object, you will be prompted to use the "Activation..." button to activate the page for your users. Follow the wizard's instructions after clicking the button.

    In Classic:

    1. Navigate to a record page, and click the “Edit Layout” link in the upper right corner of the record view
    1. In the page layout, click on the “Visualforce Pages” menu item and drag the AvochatoContactVF / AvochatoLeadVF page into a section of the record details.
      1. NOTE: Make sure to select the “Visualforce Pages” menu item and not the “Canvas Apps” menu item (if it exists).
      1. After placing the Visualforce page where you want, adjust the height to 360px for the best experience
    1. Save the page layout
  • B. Add Avochato for Salesforce to Utility Bar
    1. Go to Setup and type “App Manager” in the Quick find. Select App Manager
    1. Find the app you’d like to add the utility item to. Click on the actions dropdown menu on the far right of the app and click “Edit”
    1. In the App Settings left sidebar, click the “Utility Items” option
    1. Click “Add Utility Item” button, and choose the Avochato component in the “Custom - Managed” section
    1. Adjust the settings on the screen to your choosing, and click Save at the bottom of the page
      1. Suggested settings
        1. Width - whatever you like. 360 looks good.
        1. Height - on the Utility bar component, use 520 height, and on the Avochato component, height should be 420
        1. “Where is this component being used?” field - select “UtilityBar”
    1. Open your Salesforce app (or click back into your Salesforce page and refresh the browser), and you should see the Avochato utility bar item available for use
      1. Note: Sometimes it takes a few minutes for the cache to refresh itself
  • C. Add Avochato for Salesforce to your Gmail extension pane
    1. Requirements
      1. You need a G Suite business email address in order for the Salesforce Chrome extension to work. The extension (as of July 2019) does not work with personal gmail accounts.
    1. Salesforce Setup
      1. Go to Setup and type “Gmail” in the Quick find. Select Gmail Integration and Sync item
      1. If not already enabled, toggle the Gmail Integration to active
      1. If you click into the “Let users access Salesforce records from Gmail” section, if not already enabled, activate the “Customize Content with App Builder” toggle
      1. In the Email Application Panes subsection, edit the pane you’d like to add Avochato for Salesforce component to. If a pane doesn’t exist yet, click on the “Create New Pane” button
      1. Within the Lighting App Builder for the Email Application Pane, click and drag the Avochato component from the “Custom - Managed” list onto the pane.
        1. Suggested positioning is just under the “People” component
      1. Adjust the “Height in Pixels” setting to whatever height you’d like the component to be in Gmail. We suggest “400” pixels for smaller monitors
      1. Adjust the “Where is this component being used?” setting to “EmailClient”
      1. Click the “Save” button, and click “Activate” if it prompts you to do so.
        1. If this is the first pane page you’re creating, you can choose the “Set this page as the default Email Application Pane” radio option for your users
    1. Gmail / Chrome Setup
      1. Install the “Salesforce” chrome extension on your browser: https://chrome.google.com/webstore/detail/salesforce/jjghhkepijgakdammjldcbnjehfkfmha
      1. Open or Refresh your Gmail browser window (use Ctrl+Shift+R to reset the cache if you don’t see it immediately)
      1. Click on the “Log In to Salesforce” button and follow all the authorization steps to connect to your Salesforce org
        1. Note: If testing in Sandbox, right click the Salesforce chrome extension and click on the “Options” menu item. There you will be prompted on which environment you’d like to connect to. Select Sandbox to test in Sandbox
      1. Done! Click on an email thread with someone that’s in your Salesforce database to see the existing Avochato conversations, or start a new one, right from the Gmail sidebar extension.

IV. ⚙️ Automation via Process Builder


You can leverage the power of Salesforce Process Builder and Avochato API to automate messaging to your contacts / leads in Salesforce.

  • A. Get your Avochato API Credentials
    ℹ️
    Avochato API Credentials are on a per account per user basis. If you'd like to send a message from different Avochato Accounts, and/or different Avochato users, you can generate separate API keys for each account/user pair. In most use cases, one set of API credentials should suffice
    1. Click on the Avochato Account for the new API credentials
    1. Go into your Avochato inbox, and click on the Settings tab
    1. Click on the API Access subtab
    1. Choose an Assignee (i.e. the user that you'd like API callouts to be sent on behalf of) and click on the "Generate Auth Token" button
      💡
      If you only plan on using one set of API credentials, use the main default user or generic integration user
    1. An Auth Id and Auth Secret key will be generated. Save these for the next steps.
    1. (Optional) If you want additional API credentials for other accounts/users, repeat Steps 1 through 5 using a different account and/or assignee
  • B. Putting Avochato API Credentials into Salesforce
    1. Within your Salesforce instance, go to Setup → Custom Code → Custom Metadata Types
    1. Click on the Manage Records link next to Avochato Credentials
    1. Click the New button, and enter your API credentials as follows
      1. Label: Use the format as follows: <AccountName> <UserName> Credentials
        • Ex: DogPatch brian Credentials
      1. Avochato Credential Name will auto-format itself
      1. (Optional) Salesforce User Id: If you have a specific Salesforce User that's associated with these Avochato API credentials, put the SFID for that user here
      1. Auth ID: Copy and paste the Auth ID from step A.5. above
      1. Auth Secret: Copy and paste the Auth Secret from step A.5. above
        🛡
        We treat the Auth Secret like a password, and upon the first successful API callout using Process Builder, the Auth Secret is automatically encrypted within the metadata type record so that the Auth Secret remains secret
      1. Protected Component (checkbox): Leave this unmarked
      1. Is Active (checkbox): Mark this true. If you'd like to deactivate this API credential from Salesforce use, unmark this checkbox
      1. Is Default Credential: If this is the only API credential, mark it true. If you have multiple API credentials, mark only one of them as the default credential

      9. Click Save

  • C. Building a sample Avochato Send Message API call with Process Builder
    1. Go into Setup → Process Builder
    1. Click on the New button to create a new automation scenario, or update an existing Process Builder
    1. Create a sample process builder. We're using an Opportunity as an example
    1. Click on Opportunity as the main object for this automation. Click Save
    1. Create filters that will trigger our Avochato API Apex Action call. In our example, we'll look for any Opportunity that's Closed Won with an Amount over $10,000
    1. In the Immediate Actions section, click New Action, and select "Apex" from the picklist. Start typing in "Send Message" to see the "Avochato - Send Message" action option
    1. Fill in the message to be sent, and whom to send it to. You can use Field References to get the Owner → Phone field to send the Avochato SMS message to
    1. Click Save, and then click Activate in the upper right corner of the Process Builder
    1. Go into your Salesforce App, create a sample opportunity with the right conditions, and confirm the SMS is sent properly

V. ✨ Additional Features


1. Avochato List View Broadcasts

Send mass messages to any people within Contact or Lead List Views in Salesforce. See the page linked below for setup instructions and how to use this feature:

VI. 🤔 Troubleshooting


  • A. I put the Avochato component into the Lightning page, but nothing shows up. What happened?
    • You have to be logged into the Avochato platform first before using Avochato for Salesforce. Simply log into your Avochato account at www.avochato.com and refresh the Salesforce page
    • This also occurs if you didn't assign the Avochato for Salesforce license to the current logged in user. Assign a license to the user and refresh the page.
    • If the problem persists, stale cookies and cache can cause this issue. Log out of avochato.com, clear your browser cache and cookies, then sign back into avochato.com
  • B. My users click "Approve" within the component, but it doesn't seem to do anything. Is something wrong?
    • This is usually due to permission issues. Make sure an Avochato for Salesforce license is associated with the logged-in user, as well as assignments to the proper permission sets described in Section II above. You can also use the "Reapply Permissions" button within the Avochato Setup tab.
  • C. When I try to authenticate my Avochato for Salesforce lightning component, I get a "consumer key" error, or a refuse to connect to Avochato error in the component. What should I do?
    • This can sometimes occur if you installed the package using the "Install for Admins Only" option rather than the "Install for All Users" option, or are manually upgrading to a newer package version
    • To fix, go into Setup → Apps → Connected Apps → Manage Connected Apps
    • Click on the Edit link next to Avochato for Salesforce
    • Under the OAuth policies section, ensure that "Admin approved users are pre-authorized" option is selected. Your Avochato components will not work correctly without this setting
  • D1. Sometimes my screen has a big Canvas App error that says my session has timed out and some errors around a refresh token. How do I fix this? D2. Every so often the activity sync from Avochato to Salesforce seems to stop working, usually after a weekend or long time without activity. How do I fix this?
    • It could be due to some overly enforce IP restriction settings
    • Similar to the above issue, go into Setup, locate the Avochato for Salesforce connected app and click the Edit link
    • Under the OAuth policies section, adjust the IP Relaxation settings to "Enforce IP restrictions, but relax for refresh tokens"
    • Apply the same settings for the Avochato API app
  • E1. When editing the Lightning page (with the Lightning App Builder), I don't see "Avochato" as a custom component that I can use. Where is it? E2. When I click on the App Launcher to search for the Avochato tab, I don't see Avochato as an option. What am I missing?
    • This usually means that "My Domain" hasn't been activated within your org.
    • If My Domain wasn't the issue, and if you recently purchased Avochato for Salesforce seats on the AppExchange, you have to apply the new seat licenses to your users. See VI.H below for additional help
  • F. I'm getting an installation error when installing the package from AppExchange. What should I do?
    • Our package runs a post-install script which assumes your Salesforce org has access to "Connected Apps"
    • Check if you have access to Connected Apps. If you check Setup, you should be able to see the Setup → Apps → Connected Apps → Manage Connected Apps option. If you don't see that option, open a support ticket with Salesforce requesting access to Connected Apps. In addition, also request access to the Canvas API (to avoid the issue mentioned below in part G)
  • G. I followed all of the instructions and the Avochato Setup tab indicated that everything was configured correctly. But when I drag the lightning component onto the Lightning Page, I get a strange permissions error about "Canvas API". What is that and how do I fix this?
    • Our lightning component uses a Canvas Connected App, which allows for secure communications between Salesforce and Avochato
    • If you get this "Canvas API" error, open a support ticket with Salesforce requesting access to Canvas API
  • H. I installed the Avochato for Salesforce app, did the trial, and am now ready to buy seats. Where do I go from here?
    • Go to the AppExchange, login as the user who installed the package originally, and then click on our Avochato for Salesforce listing
      ⚠️
      If you're having login issues on the AppExchange, see Section VI.K below for assistance
    • There should be a green button on the right side of the page that say "Buy Now". Click that button
    • Follow all the instructions on the wizard to enter the number of licenses you'd like to purchase and payment information
    • After completing this step, make sure to follow the instructions in Section II.2.A to apply your newly bought licenses. If you don't apply the licenses, Avochato for Salesforce will no longer work properly as it did during the trial period
    • To double check all your settings, click into the Avochato Setup tab within Salesforce and that page should confirm your settings are filled in correctly, or instruct you on how to finish setup
  • I. After purchasing seats on the AppExchange, the Avochato & Avochato Setup tabs disappeared from the tab bar and the app selector. What happened?
    • When you install Avochato for Salesforce the first time around, you have a 7 day unlimited use trial. Once you buy seats, you have to apply those seat licenses to Salesforce users in order for those users to continue using Avochato for Salesforce
    • Follow the instructions in Section II.2.A above to assign Licenses to the Salesforce Users you would like to have access to Avochato for Salesforce. The tabs should reappear after applying the License
    • You can also double check the Avochato Setup tab to ensure your users have all the other permissions they need to use Avochato for Salesforce.
  • J. After installing the app from the AppExchange, and then trying to setup the Avochato Salesforce sync integration specified in Section I.C, I'm shown an error page, and the browser URL has an error message OAUTH_APP_ACCESS_DENIED. How do I fix this?
    • Settings and permissions within Salesforce may not have been setup correctly, causing this error
    • To fix, ensure the Avochato_API connected app has the "User Approved" setting for the OAuth Policies section.
      ⚠️
      Make sure you're adjusting the Avochato_API app to this User Approved setting, and not the Avochato_for_Salesforce app, which should have the "Admin Approved" setting.
  • K. Everytime I try to login to the AppExchange in order to buy my Avochato for Salesforce seats, I get an authentication error message and I don't know where to go from here to get my seats.
    • In order to buy app seats from the AppExchange, you need to have setup a Trailblazer profile for your Salesforce login
    • Follow the instructions to "Sign Up" in order to create a new Trailblazer account and associate it with your Salesforce user
  • L. When trying to buy licenses for Avochato for Salesforce the first time, anytime I login and go to the Avochato for Salesforce listing on the AppExchange, it shows the "Get It Now" button, even though I've already installed it. I'm supposed to see a "Buy Now" button. What should I do?
    • To buy Avochato for Salesforce seat licenses, you must use the external website www.appexchange.com to purchase the licenses, and shouldn't use the built-in AppExchange from within Salesforce itself
    • In www.appexchange.com, make sure to login with your Salesforce Login credentials. You may have a Trailblazer account which is separate from your Salesforce Login, and you need your Salesforce Login account in order to purchase licenses
  • M. After the Winter '21 release in October 2020, some of our users suddenly couldn't see the Avochato for Salesforce lightning component on their Salesforce record pages. What happened?
    • Winter '21 enforced some new security measures around lightning components that require additional permissions
    • Any Avochato for Salesforce package install with version 1.17 or later will have this fix
    • For anyone on package version 1.16 or earlier, you can do the following:
      • Go into Setup " Users " Permission Sets
      • Click into "Avochato Connected App User"
      • Click into the Apex Class Access link
      • Click on the Edit button to add a new Apex Class
      • Bring the Avochato.AvochatoController class into the Enabled Apex Classes section and click Save
      • Done! All the users with the Avochato Connected App User will now have access again to the Avochato for Salesforce lightning component
  • N. I've installed Avochato for Salesforce but I don't see the Avochato or Avochato Setup tab. What can I do?
    • Assuming My Domain is enabled (see Section VI.E2 for more details), the Avochato tabs can be enabled via Permission Sets
    • Click into Setup → Permission Sets
    • Click on the "Avochato Connected App User" Permission Set
    • Click into "Object Settings", usually the third option on the screen
    • Click into the "Avochato" item, then click Edit
    • Mark both checkboxes true for Available and Visible, then click Save
    • Repeat the same steps for the "Avochato Setup" item
    • Done! Refresh your page and you should be able to see the Avochato and Avochato Setup tabs in the App Selector
    Note: You may have to reset your cache for the page, or log out and log back into Salesforce in order to see the tab updates.
  • O. I've used List View Broadcasting successfully in the past, but recently got a strange Publish Error message about a null reference. What's the issue?
    • Broadcasts have two steps - prepping the broadcast and then publishing it. Depending on the size of the broadcast and the queue in Avochato servers, that prep broadcast might take longer than the command to publish the broadcast
    • If this is a common occurrence, wait some time (20-30 seconds) before clicking the Publish Broadcast button.
    • If still an issue, reach out to your Avochato representative for further investigation.