Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This section allows you to set up the platform to receive emails from users. Before getting started, make sure that you have an email account set up on Gmail, Yahoo or any other service provider. Make sure that you have IMAP/POP enabled (For more information on these two protocols, visit this website. Instructions on how to enable the IMAP/POP settings in your email can be found here
Gmail settings: Follow this guide to enable IMAP from external clients with Gmail. Keep in mind: There are a few settings you need to configure so that Ushahidi can pull from a Gmail account.
Step 1: Check that IMAP is turned on
On your computer, open Gmail.
In the top right, click Settings See all settings.
Click the Forwarding and POP/IMAP tab.
In the "IMAP access" section, select Enable IMAP.
Click Save Changes.
Step 2: Check that Two-Factor Authentication is turned on One needs to have Gmail's Two-Factor Authentication enabled. Visithttps://www.google.com/landing/2step/ if you do not have it enabled for your account.
Step 3: Create an App password This is a 16-digit passcode that gives a non-Google app or device permission to access your Google Account. (Google Docs here:https://support.google.com/mail/answer/185833?hl=en-GB)
On your computer, open App passwords
When prompted for "Select the app and device you want to generate the app password for":
Select “Mail” under the drop-down for “Select app”
Select “Other” under the drop-down for “Select device”
When prompted for text input, enter your Ushahidi deployment name
(e.g. The name of my deployment is Free Media, I’ll enter “Ushahidi Free Media ”).
Copy the password to your clipboard that is automatically generated and save it somewhere (we would need this later).
Yahoo settings: Yahoo
Email setup on Ushahidi platform
To get started with email the setup, click on the add source button on the top right as shown and select Email.
Input the following email account settings
Incoming server type: You have two options to select from, POP and IMAP. We recommend using IMAP if possible because it’s the best way to make sure you can see all your mail at any time on all of your devices
Incoming server: Enter the address of the server where your email services are hosted. E.g mail.yourwebsite.com and for Gmail: imap.gmail.com
Incoming server port: Enter the port that your email account uses for incoming emails. This is also provided by your service provider and depends on the use of SSL(Secure Sockets Layer)/Transport Layer Security(TLS) or not. As a standard rule;
Enter 993 (Since we’re using IMAP) for Gmail.
POP uses port 110 , but SSL/TLS encrypted POP uses port 995
Incoming server security: You have 3 options to choose from to enhance secure connection to your email mailbox, depending on which is supported by your email service provider.
None
SSL - Read more on Secure Sockets Layer for Gmail
Incoming user name: Enter the email address you want to use to receive emails e.g sample@youremail.com. We recommend setting up a separate email address for this purpose, preferably one that has a lot of available space to avoid the account getting full in a short time, especially if the platform will be receiving a lot of submissions via email.
Incoming password: Enter the password of the email account inserted above. Enter the “App password” generated above for the gmail account.
Next:
Click on Save and this data source’s settings will be saved. Unstructured posts from email will now be pulled into the platform.
If you’d like to edit your email configuration, simply click on the the email data source to see the edit form, and make your changes.
If you no longer want the email data source simply click on the data source as if you want to edit it and the use the delete button.
Note: Reports coming via email will take a while before they reflect on the platform because there is a “job” that needs to be run in the database and those jobs run every 10 minutes or so.
We are having some issues with the play store at the moment, you can download the SMS Sync app at https://github.com/ushahidi/SMSSync/releases/download/v3.1.1/smssync-withAnalyticsRelease-v3.1.1-RELEASE.apk
SMSsync is a simple, yet powerful SMS to HTTP sync utility that turns any Android phone into a local SMS gateway by sending incoming messages (SMS) to a configured URL (web service).
Please note that SMSsync works on any SMS-enabled device running Android 2.1 and above.
Once you have downloaded it, click on install to save it on your phone.
Open up the SMSSync Application on your android device, click skip or swipe left, and click done to continue.
On the incoming messages screen, click on the arrow at the bottom right corner to enable SMSsync.
Once you have enabled SMSsync, you will be redirected to the integrations screen. Start the SMSSync Service to start fetching messages in your app.
Click on the custom web service to configure SMSsync with your deployment.
Manage custom web services screen will open, you’ll note that you can manage multiple Sync URLs on the app.
To add a new Sync URL, tap on the Add icon on the actionbar. An input dialog should open.
Open your deployment i.e name.ushahidi.io, go to datasource configuration in your setting page.
Click on the drop down icon on the right as shown
Follow the instructions given to you below.
You will need the Sync URL to configure SMSSync.
Set a SMSSync secret key for security purposes.
Click on Save.
To enable/disable this datasource , simply click on the green toggle to accept survey submissions.
Click on the toggle to import your messages' response to a survey.
Select the survey you wish to import your messages to.
Select which field should be assigned to populate the data from SMSsync.
Go back to the input dialog on your SMSsync App and add the following details;
Title for the custom service: This can be the name of your deployment or any title you see fit
Custom web service Url: Enter the Sync URL in step 2 from your deployment as shown in the 'Android settings' image above i.e "https://yourdeploymentname.api.ushahidi.io/sms/smssync".
Secret key: Make sure you enter the exact key as the one you entered in your deployment android setting as shown in the 'Android settings' image above.
Once you enter your secret key, you are done with the configuration, do not change the rest of the settings.
Click ADD or test integration to save the new entry.
Nb:The secret key should be presented as string of any characters without spaces. Enter a comma separated value for the keyword(s). These keywords will be used by SMSsync to filter incoming SMS and pending messages to the Sync URL you are adding. As of v2.0.2. You can now add Regular Expression code for filtering. This means, it can either be CSV or RegExp. It cannot be both.
Note: Version 2.5 or higher supports basic auth credentials in the URL, e.g. https://username:pass@example.com/api-v1/add-record/.
You will now need to start the SMSSync Service to start forwarding messages to the platform. To start the SMSSync service
Make sure that you have added and enabled(checked) the Sync URL you added above.
On the integration screen, tap on the Start SMSsync service to start the service if you had not enabled it.
You should be all set to work with SMSSync and Ushahidi now. Unstructured posts via SMS will now be pulled into the platform.
If you’d like to edit your SMSSync configuration, simply click on the drop down icon on the right while on the data sources list page and make your changes.
For more details on how to manage messages within SMSSync, see configuration instructions on the SMSSync Website
This data source is not available in your deployments. You will not find it in your settings, please reach out to support@ushahidi.com or our chat messenger to enable it in your deployment.
This section allows you to set up the platform to receive and send emails through a connected Gmail account via the API. Before getting started, make sure that you have an email account set up on Gmail. Note: If you're self hosting the Ushahidi platform, the Gmail Provider makes use of the server-side flow when making a request to Gmail API, and must be authorized using OAuth 2.0 Credentials.
Follow this guide to create the OAuth 2.0 Credentials (Client ID and Client Secret) with Gmail. Keep in mind:
Select "where you will be calling the API from" as Other UI.
Select User data as the data type to be accessed.
Select your application type as TVs and Limited Input devices.
There's a need to set up a consent screen.
To get started with Gmail set up on the Ushahidi platform, click on Gmail from the drop down as shown below.
Input the following email account settings
Email Address: Enter the Gmail address you will be receiving and sending emails with.
Fetch Email From: Pick the date you want to start fetching messages from.
Client Id: Enter the Gmail client id gotten from the OAuth credentials.
Client Secret: Enter the Gmail client secret gotten from the OAuth credentials.
Redirect URL: Enter the redirect URL from the OAuth credentials. The default value set here is urn:ietf:wg:oauth:2.0:oob and in most cases should be left this way.
Click on Save and this data source’s settings will be saved.
The below setup will be available to both the hosted and self-hosted users.
Next, Scroll up and click on Connect your Gmail Account and this will show a google prompt to authenticate your Gmail account.
Follow the prompt through and click on Allow to be presented with the list of Gmail accounts that you have.
Grant permission by selecting the Gmail account that you would like the Ushahidi platform to access.
This will display an auth code.
Please copy the provided code, switch back to your Ushahidi application, and paste/enter it on the opened modal:
Enter the point in time that you would like the Ushahidi platform to fetch messages from your inbox.
Click on Authorize to save the auth code and date entered.
A message will be displayed in your deployment to indicate that your account is connected, messages from Gmail will now be pulled into the platform via the API.
To disconnect your account, simply click on Disconnect your Gmail account to stop all messages from being fetched from your inbox.
NB: All messages that were previously fetched will not be deleted from your deployment.
To enable/disable the email data source, simply click on the green toggle and click on save.
Data sources may contain outdated information. Work is ongoing to fix the content of this page.
There are many ways to enter posts into your Ushahidi deployment other than from the deployment itself. This section shows you how to configure all the possible data source types.
To access the data sources configuration page, on the sidebar, click on Settings
Then, click on Data Sources
You should get a full list of data sources as shown below
In this section you will learn how to configure different data sources to your Ushahidi deployment.
Vonage is a cloud-based SMS API that lets you send and receive a high volume of messages to mobile phones in any country at wholesale rates.
NB: You need a nexmo account to be able to configure this as a data source. To sign up, go to (https://dashboard.nexmo.com/sign-up)
To get started with Nexmo set up,
Log into your Vonage Dashboard https://dashboard.nexmo.com
If you haven’t already, you’ll need to buy a number that you will use to receive SMS messages from.
Click on Numbers on the top menu bar on your Vonage dashboard
Click on Buy Numbers
Set the desired criteria of the phone number you’re looking to use
Select the country in which the SMS Number will likely be operating in
Select the features of this phone number(SMS only, Voice only or SMS & Voice)
Select the type of phone number it will be (Mobile, Landline, Toll free)
Click on search. A list of available numbers based on the criteria set above will appear.
Click Buy on the number you’d like to use.
Once you have a phone number, note it down as you’ll need it to configure your data source later on.
You’ll need to grab your API credentials from your nexmo settings page.
Pick your API KEY and API SECRET from the API Settings section.
Go back to your Data source settings page on your deployment
Click on the drop down icon on the right to get to your Nexmo configuration page
Enter the following details, which you got earlier from your Nexmo Dashboard
From: Enter the phone number you will use to receive SMS messages from your nexmo account
API KEY: Enter the API key retrieved from your nexmo settings page.
API SECRET: Enter the API secret retrieved from your nexmo settings page.
Click on Save **and this data source’s settings will be saved. Unstructured posts from SMS will now be pulled into the platform from Nexmo.
To enable/disable the Nexmo data source, simply click on the green toggle.
If you’d like to edit your Nexmo configuration, simply click on the drop down icon on the right while on the data sources list page and make your changes.
Go to https://dashboard.nexmo.com/settings where you can set up the webhook. This is where we can make Nexmo aware of the existence of your Ushahidi deployment and help them connect with each other. Enter the sync URL i.e “https://yourdeploymentname.api.ushahidi.io/sms/nexmo” on the inbound SMS webhook field as shown below and save changes.
Twilio allows you to programmatically make and receive phone calls and send and receive text messages using its web service APIs.
NB: You need a Twilio account to be able to configure this as a data source. To sign up, go to **[_https://www.twilio.com/try-twilio**_](https://www.twilio.com/try-twilio)
To get started with Twilio set up,
Log into your twilio account.
You’ll need to buy a number to use. Click on the hashtag icon
Click on the red "Plus" icon.
Select the desired criteria for your phone number In the number selection/purchase screen
Select the country where you need a phone number. This is the number that people will use when sending a report through SMS.
Location/Number: You can search numbers by digits/phrases or by location. This is optional.
Capabilities (Voice, SMS, Fax, MMS): Make sure you tick the "SMS" checkbox. We want to make sure Twilio only shows us numbers with SMS capabilities. If it can't be ticked/clicked, then it means that Twilio doesn't have any numbers with SMS capabilities in that country.
Click on **_Search**_. A list of available numbers with their rates based on the criteria set above will appear
Click Buy on the number you’d like to use.
You will be shown a screen like this one below where they confirm all capabilities, the number, and other details.
Click the buy button at the bottom right hand of the screen to purchase your number.
Once you have a phone number, note it down as you’ll need it to configure your data source later on.
First, we need to get the following information from your Twilio account:
Phone Number: the number you just purchased. If you forgot it, you click the "Hashtag" icon in Twilio again to see your available numbers.
Account SID
You will see a panel like the one below with details about your project. Get the Account SID from it (we've highlighted it in the screenshot as a reference)
Auth Token
In the same panel as the account SID, you will see a "view" link next to "Auth token" as shown on the diagram above.
Click it, and it will display your account's auth token.
Next, with the Account SID, Auth Token and Phone number you just obtained:
Go to your Datasources settings page on your Ushahidi deployment.
Click on the drop down icon on the right as shown
You will see a list of fields like this one
Enter the following details, which you got earlier from your Twilio Account
From: Enter the phone number you got from Twilio.
ACCOUNT SID: Enter the account SID of your Twilio account
AUTH TOKEN: Enter the Auth Token retrieved from your Twilio account Dashboard page
SMS Auto Response: This will be sent automatically when a user sends a message to your Twilio number. You could use it to provide reference information, like thanking the user or just confirm receipt.
Click on Save **and this data source’s settings will be saved. Unstructured posts from SMS will now be pulled into the platform from Twilio.
To enable/disable the Twilio data source and choose which survey to import to, simply click on the green toggles.
At this point, your Twilio setup in Ushahidi Platform is ready to use but we need to do some follow up tasks in Twilio to connect both of them.
Go to https://www.twilio.com/console/phone-numbers/runtime/twiml-apps where you can create Twiml apps. This is where we can make Twilio aware of the existence of your Ushahidi deployment and help them connect with each other.
Click on the red "+" button to create a new app. You will see a screen like the one below.
Fill in these details;
Friendly name: Write down a name that helps you remember what this app does. We usually choose the deployment name as the "friendly name" in Twilio.
Messaging: In this **section you will need to add your deployment's Twilio endpoint URL. This is the API Url to your deployment + the endpoint to connect to.
For Ushahidi.io deployments, the rule is always the same. Given a deployment with the following url "https://**yourdeploymentname**.[ushahidi.io](http://ushahidi.io)" + the API Url will be = "https://**yourdeploymentname.api**.[ushahidi.io](http://ushahidi.io)".
Follow this formula to get your Request URL:
Your deployment URL: "https://**yourdeploymentname**.ushahidi.io"
The API URL: "https://**yourdeploymentname.api**.ushahidi.io"
The Request URL then would be "https://yourdeploymentname.api.ushahidi.io/sms/twilio". is what you will enter in the "Request URL" field.
After you are done with adding Messaging and friendly name, you can click the red "Save" button.
Go to your list of active phone numbers and click on the number you purchased https://www.twilio.com/console/phone-numbers/incoming
Click on your number.
Scroll down and you will see a form like this one.
In the configure with field: Select TwiML App
in the TWIML APP field: Enter the Friendly name you created above for your deployment. This will ensure that when you get an SMS, Twilio sends a request to Ushahidi platform to save the message.
Send an SMS to the phone number you purchased and configured (ie from your own phone).
You can validate that messages are getting to Twilio by going to the Programmable SMS logs https://www.twilio.com/console/sms/logs
You will see the messages your Twilio number has received and sent in the list
The list will look like this. You can click on the red link under "Date" to see the details of each message.
Example of a single message below.
Go to the Ushahidi Platform
Go to the data view
You should see the messages you sent in the data view list
This section allows you to configure Africa's Talking as a data source and receive SMS messages as unstructured posts in your Ushahidi deployment.
Login to Ushahidi.
Click on Settings -> Data Sources
Click Add source
Select Africa's Talking
Enter your Username, API Key, and SMS Short Code, and then click Save.
Login to Africa's Talking Dashboard and click on app
Click on SMS -> Callback URLs -> Incoming Messages
Enter the Ushahidi's callback URL and click Submit.
The URL is your deployment backend's API URL, ending with "/sms/africas-talking"
The API URL is often slightly different from your deployment's website URL.
If you are using the ushahidi.io hosting service, you will always need to insert ".api" after your subdomain. Example:
Assuming your deployment's URL address is My-Deployment.ushahidi.io
The API URL for your deployment would be: My-Deployment.api.ushahidi.io
Consult with your system administrator if you are configuring a deployment hosted outside of ushahidi.io
Don't forget to append "/sms/africas-talking" to the resulting API URL
e.g. https://quakemap.api.ushahidi.io/sms/africas-talking
This section allows you to configure Twitter as a data source, and subsequently pull unstructured posts from specific Twitter hashtags.
For you to be able to pull tweets based on hashtags, you will need to set up your Ushahidi deployment as an application on Twitter. To get started,
Click on the drop-down icon on the right as shown
Click on Create a new Twitter application. This will redirect you to https://developer.twitter.com/en
Sign into https://developer.twitter.com/en using your Twitter username and password.
Click on the Developer Portal to take you to the page where you will create your app or visit https://developer.twitter.com/en/portal/dashboard
Once you select the Developer Portal, you will be directed to your portal immediately. If you haven't created a developer's profile yet, you will be redirected to sign up for one as shown in the picture below:
From here, you can choose either to Sign up for Free Account or choose one of the paid tiers to subscribe to. Note that the free tier limits the feature sets offered in these other paid tiers. Check their website for more information: https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api
Once you select the option Sign up for Free Account, you will need to describe your use cases and also agree to the terms and conditions stipulated.
Once you have filled in your description and checked all the boxes, click Submit.
Once you click Submit, your developer account will automatically be created and you will be redirected to the Developer's Portal. Here, you will find out that Twitter/X has already created a project for you together with the app. You can proceed with this one, or you can delete the pre-made project and create yours afresh. If you decide to delete it, you can create a new one as shown below.
Once selected, you should give your project a name
Afterwards, select your use case for how you intend to use the platform
Provide a brief description of your project
Once you are done, you should click Next to set up your app.
To set up your app in this project, follow the steps below;
Select your App name.
You can enter the name of your deployment to make it more memorable.
Click on Next to generate your keys and token.
Here, you will see the API Key, API Key Secret, and the Bearer Token generated for your app. Make sure to master or note down these codes safely since you will use them when filling out the form in the Ushahidi Platform. These codes can be generated later on as we will see in the process down below. Keep in mind that regenerating these keys might need you to update your code for your app to work properly.
Note: The API Key and Secret Key are treated like passwords, therefore they should be memorized or saved in a secure location. If the security has been compromised/you forgot to save the keys, new ones can be generated.
Go to Overview https://developer.twitter.com/en/portal/projects-and-apps, adjacent to your project app name, there is a Key icon, click on it to view your API and Access token keys. These will be needed to configure Twitter/X with your deployment.
You’ll get redirected to a page where you can grab details needed to configure your Ushahidi deployment i.e CONSUMER KEY, CONSUMER SECRET, ACCESS TOKEN, ACCESS TOKEN SECRET.
Go back to your Twitter configuration page on your deployment and fill in all the details from your Twitter app management page.
On your Twitter developer account panel, click on Reveal API Key hint next to API key and Secret to display a hint of your API Key. If you had not captured these codes before, you will be required to generate new ones. Copy and paste them on your deployment API and secret fields.
On the same panel, you will see Access Token and Secret. You’ll have to generate an ACCESS TOKEN and ACCESS TOKEN SECRET by clicking on the Generate button.
Copy and paste them on your deployment ACCESS TOKEN and ACCESS TOKEN SECRET fields.
NB: if you save them without copying and pasting, you will be regenerating new ones.
Add the hashtags you want to pull tweets from in the Twitter Search Terms section. You can choose more than one hashtag, separated by a comma. It is recommended that short and clear hashtags be chosen.
Click on Save and this data source’s settings will be saved. Unstructured posts from Twitter will now get pulled into the platform.
To enable/disable the Twitter data source, simply click on the green toggle.
If you’d like to edit your Twitter configuration, click on the Twitter option and make your changes. Once you are done click Save. You can also delete Twitter as a data source by selecting the delete button.
You can also choose which survey you want to import the data source into and you can toggle the option of accepting survey submissions from this source.
It will only take a few minutes and the tweets will appear on your deployment.
