Community Testing Best Practices (API)

Overview

Congratulations! You’re in the process of configuring your Community, and perhaps developing some key integrations to make sure you get the most value from the product, and that it fits seamlessly into your infrastructure. You’ll want to test the functionality to make sure that everything is working as expected. Here are some best practices to make sure your testing is effective and safe!

 

---

 

Testing Environment

Why Test in Production?

While other tools recommend that you work and test in sandbox environments, this is often not advisable in the messaging space, since provisioning an environment requires a telephone number, which requires TCR registration. Your best bet is to test in your production account. That has a few implications for testing:

First, this is a real, live service flowing from your registered number, through the carriers, to your test numbers – so make sure you are testing with compliant content in accordance with what is allowed over messaging as described in our Acceptable Use Policy. 

Test with your own known numbers: Use U.S. or Canadian mobile numbers (e.g., personal or Google Voice numbers).

VOIP services like Google Voice are useful for non-U.S. team members. With VOIP services, however, you may experience:

• • • • Messages getting sent to spam
      • Attachments, like .vcf contact cards, may get stripped from the message.

 

---

 

What Are You Trying to Accomplish?

Common Use Cases and API References

Let’s start with what you’re trying to accomplish. Use the links below to access detailed API documentation for each Use Case.

Managing Members and Sub-Communities via API

I want to add new members from my API or a form I host on my website

Use the Invite / Update Member API to add new members to your Community programmatically. This uses the phone number as a key identifier. If the Member already exists in Community, you have the ability to update their data using the same endpoint. 

I want to manage Subcommunity segments via API to Add and Remove members within these member segments

Use the Change Community Membership API to assign members to different Subcommunities. 

You can also Create, Delete, and Update subcommunities via API.

I want to opt out a member via API

Use the Opt-out Member API to remove members from your Community, using phone number as the key identifier. 

I want to add custom profile properties for my members

Store and manage custom member properties with the Custom Member Data API.

Sending Messages from an external system via API 

I want to send messages triggered from my external system

Trigger outbound messages with the Send Message API.

Tracking Events, Listening to Messages, and Data Management

I want to download data via API

Retrieve Community data reports such as Campaign performance, Member details, Subcommunity Membership, and more with the Data Export API.

I want to listen to Inbound Messages, Outbound Messages, and Member Events in real-time

Utilize Community Webhooks to capture and respond to events as they happen.

 

---

 

Essential Testing Practices

1. Organize your test numbers into a sub-community that is exclusively used for testing and is labeled clearly as such. Direct all test campaigns to this sub-community:

 

Please note, you can make as many communities as you need for testing. Your account, by default, is allowed up to 200 communities, and communities can always be deleted after the fact. 

2. Test All Member Creation Flows: Members can be created in a number of different ways and from a number of different sources. The entry point also can make a difference in the initial sign-up series experience that they receive, depending on your configurations. These entry channels include:
   • • • Text-in to join (including QR code flows): Member initiates activation either by texting in directly to your Community number or scanning a QR code that will then prompt them to text in directly. 
       • Added via Integration (Webhook or API): Members created via integration from a third party tool (CRM, marketing automation tool, etc.) or from an integrated external web form. 
       • Bulk upload (via Community Support): Are you migrating members from a previous tool, CRM or other database? 
       • Zapier integration: If you are a Zapier user, you can use Zapier to pass us new Members!
       • Pre-opt vs. not pre-opt: Are you gaining TCPA-compliant opt-in from your integrated or uploaded Members upstream from Community? If so, we can bypass the opt-in process on our Platform (pending a quick Compliance review). 

Make sure to test all of those inbound new Member channels that you intend to use. If you’re unsure about what’s best, reach out to your Account team or yourfriends@community.con for more information. 

3. Testing the opt-in flow multiple times from your test number. Community has protective logic that will remember former Members who had subscribed and then asked for their profile to be deleted. We will, for a time, prevent them from being resubscribed to the number they opted-out of via API, webhook or bulk upload. (Note: The cooldown period does not apply to numbers who text in manually to subscribe. They will be taken through the registration process regardless). 

This function is meant to help ensure we honor our Members’ opt-out decisions and prevent accidental re-activation. However, it can be frustrating when you are testing and want to try the opt-in flow multiple times from your test number. Here’s how to manage around this with test numbers: 

• • • • Before testing, subscribe to your own Community phone number with the testing devices. This can be done by either manual text-in, or by import/integration, just make sure that no matter what method you use, you complete the process all the way to the point that you receive the welcome message and contact card. 
        • • • • For manual text-ins, this most often includes filling out and submitting the registration form that is sent to you in response to your text. 
              • For imported numbers, this often includes a "Reply Y" confirmation step. 
              • (These options may vary based on how you configured your sign-up series, if you have questions, feel free to reach out to yourfriends@community.com.)
      • Next, from the test device(s), text the following message to your Community number:“ENABLE COMMUNITY IMPORT TESTING ON THIS DEVICE”.  This command will flag that number in our system so that the import logic will ignore the cooldown period when they are imported (then deleted) repeatedly. You can enable any "live" test device by following this process. 
        • • • • If you had deleted a "live" test device before you enabled it for import testing, the only way to restart that number is by text in START to your Community number from that device/number. Once it's reactivated, you're free to enable it for import testing as described above. 

Then, for 10-digit long-code Community phone numbers, when you’re ready, we have a simple way to remove a Member’s information from the database entirely – which will allow you to re-subscribe and re-test using that number again immediately. This process can be repeated as many times as necessary:

• • • • Text HELP and click the “Manage Preferences” hyperlink that is sent in reply. Scroll to the bottom of the profile update page, and select  “Delete my Data.”  
      • Do not text in STOP in order to delete your profile. It will not delete the profile, but set it to inactive for that Community number, and they will not be able to be added again via integration or upload beyond. 

 

Note: If you have a short-code rather than a 10-digit long-code, you'll have to email yourfriends@community.com for help deleting test member account data, when needed.

 

4. New Members must opt in. When testing the Add New Members function, remember that the “new” Members will have to opt-in before they become a “live” Member, and before they show as a Member in the system. Please see this guide to Member states for reference.

• • • • For Members created via API or Webhook:
        • • • • If you have coordinated with our team to configure your onboarding process to use “Reply Y” consent, then they will have to “Reply Y” before they are considered a live Member.
              • If they are “Pre-Opt,” which means proper consent was gathered and approved at time of phone number capture (usually your web form), then the Member does not need to take any further action before they are considered a live Member. 
              • If “Reply Y” nor “Pre-Opt” is something you discussed with the Community team. Please reach out to yourfriends@community.com for configuration of your Member onboarding flows. 
      • For Members created via direct text-in, they will have to submit the Member registration sign-up form before they are considered a live Member.

5. When trying to send a message via API, you may need to override Quiet Hours. We enforce official Quiet Hours, night time hours when people may be asleep or otherwise not wish to receive text messages. 

• • • • Community’s Quiet Hour Protection will be applied to messages that:
        • • • • Direct Messages sent via API unless overridden in the POST request (see below):

• • • • • • • Automated messages (including “Setup Series” messages) where the “Do not send message(s) during quiet hours” option is checked on the message settings.

Community’s Quiet Hour protection will not be automatically applied to:

• • • Initial onboarding messages
    • Standard system messages (such as “help,” “stop,” etc.) 
    • Direct messages
    • Campaigns/scheduled campaigns (though you will be prompted to validate the timing if it’s during quiet hours.) 

6. Testing Opt-Outs
   • • How it works, generally:
       • • • Texting STOP to a Community number from any subscribed Member number will deactivate the Member from that particular subscription (only). 
           • That Member’s profile will remain, including their opt-out history. 
           • They will be blocked from being re-subscribed to that same Community account via API/import, since they have requested to be opted-out.
           • However, de-activated Members can always manually text-in to resubscribe themselves at any time, regardless. 
     • How to test Opt-Outs on numbers that will be reused for import testing:
       • • • Before you begin, make sure you follow directions in section 2 of this document for preparing a number for import testing. 
           • After having opted-out from a subscribed test number, text HELP from that de-activated number, and follow the directions in section 2 of this document for deleting the Member’s profile. After such, you are free to use that number again for import testing.

 

Getting API Access, Tokens, and Authentication

If you are building an integration, you’ll need to generate an API Token from within the Community UI to leverage along with your Customer ID (client_id) for authentication purposes in the web service. 

See here for more direction:

I don’t see the “API Token” menu option in my Community Settings 

• API Access is granted both at the account level (for plans which include the functionality) and at the individual “seat” level. Please work with your account team or email yourfriends@community.com to make sure you have all the permissions you need. 
• Who is on the testing team? Have they been added as a seat on your account, and have they accepted that invite? 
• Still not seeing the functionality you need? (API access, webhooks, data download, Zapier, etc.)? Email yourfriends@community.com, or speak to your Account Manager to confirm the appropriate seats are assigned these advanced permissions. if any of these advanced permission changes are required. They are controlled by Community administrators on a per-seat basis. 

How often do API tokens expire? 

• Tokens are generated on a per-seat basis and only visible to that seat.
• Tokens refresh for 12 months on every use. They can be refreshed indefinitely. A token will automatically expire if it hasn't been used in over a year.

 

---

 

Other tips that may be helpful when testing

• Make sure to test both the positive and the negative use cases.
• Who will you send test messages to? Are those users live Members of your Community? If not, how will you add them (via API, direct text-in sign up, bulk upload)?
• Try adding users both via manual text-in and integration and/or upload functions. The Signup Series vary slightly by method, so validating the welcome message variations is a good idea.
  • Note: yourfriends@community.com will have to help with batch Member uploads, if that’s applicable to you.
• Test all of your integrations – including both inbound and outbound. Make sure to validate on both ends of the integration. 
• Are you testing SMS and MMS? If so, remember, MMS messages can only be sent via the Community user-interface and not via API.
• If you are using Custom Member Data fields, the custom field(s) need to be first created manually from within the user interface. Please see this help doc for reference. 
• Likewise, if you plan to send Member “tags” via the Create/Update Member API, make sure you have created the applicable sub-communities via the user-interface in advance.
• If you are connecting Formstack, make sure to use standard Formstack fields in your forms, and do not rename/re-label them. Breaking the standard fields and field naming conventions will prevent Community from parsing the form data.

 

---

 

Troubleshooting & FAQs

• I don’t see the “API Token” menu option in my Community Settings. 
  • • API Access is granted both at the account level and at the team “seat” level. Please work with your account team or email yourfriends@community.com to make sure you have all the permissions you need. 
• My API call is not working.
  • • Make sure that in the POST Request, you are including your API “bearer” token in the header and your Customer ID (client_id) in the URL. Also make sure that the end-point matches those we provide in our API documentation. Sample:

• Lastly–check the response you’re receiving:

• I sent a New Member request via API and the response back was “202” (accepted), but I’m not seeing the member in my Community.
  • • Remember, members will be received, but not activated until they opt-in UNLESS you have set up pre-opt with your account team. Until they are activated (i.e. Reply Y), you will not see them as a member in your community.
• I’m creating a new member via QR code or direct-text in, but they are not showing as a member in my Community.
  • • Same as above: Members will be activated until they opt-in. Until they are activated (i.e. they fill and submit the registration form), you will not see them as a member in your community.
• I have connected Formstack, and I have set up “pre-opt,” but I’m still not seeing the member come through to Community (or I see it and there is data missing).
  • • The Community/Formstack connector is looking for standard Formstack fields with standard field names. If you have used a custom field, or if you have customized the field name of a standard field, Community cannot parse the data that comes in and the member will either not be created or they will be created, but may be missing data elements that you sent through. 
• There is a delay in my campaign being delivered.
  • • If a campaign is being sent (or scheduled to send) during quiet hours, make sure the “Do not send message(s) during quiet hours” option is UNCHECKED. If not, these messages will be queued and sent once quiet hours expire. 
    • If the message is sent via automated flow, make sure you have not built an unintended delay into your flow logic. 
• We use a short-code phone number rather than a 10 digit long code, are there any differences from a testing perspective?
  • • There are no impacts to administration of your account or in testing strategy due to short-codes. 
• How can I delete a community after one is created? 
  • • There are five default communities that are present upon activation of your account, and which can’t be deleted:
      • • All Members
        • Favorites
        • Shopify (contains Members who joined from your Shopify checkout)
        • Web Visitors (contains Members who joined from our embedded sign up unit, if applicable)
        • Joined After Calling (Includes Members who joined via the automated redirect after they phoned your number via voice, if activated)
    • All other custom communities can be deleted from inside the Community User Interface. To do so:  
      • • Navigate to the Communities section, select the community you wish to delete > click the ellipsis in the upper right corner of the screen > select Delete Community.

 

---

 

Platform Partners

I am a partner platform looking for access to an account to test our integration with Community.

If you are a partner platform looking for access and do not have an account as a customer, reach out to yourfriends@community.com and we will discuss getting you access for testing and documentation.