How to Setup Generic SMS Gateway

iammash · 14 September 2023 19:24

Hi All,

I am trying to configure a generic sms gateway using a local provider, at the moment, I just need to set up for outbound sms. I have looked at similar posts here as well as the documentation. but for some reason, I am not able to get it working.

The provider documentation url is as below (working fine in post man)
https://url/api/v2.1/action/send/api_key/api_key/contacts/contacts/senderId/sender_id/message/message

where:
contacts is the number(s) to send the sms, 26095000xxxx or [‘26096xxxxxxx’,’26097xxxxxxx’]
sender_id is a text string configured on their platform, basically the name the msg appears to be from
message is the actual sms being sent

so I changed a few parameters like below

https://url/api/v2.1/action/send/api_key/{api_key}/contacts/**{recipient}**/senderId/**{senderId}**/message/**{message}**

Url template: https://url/api/v2.1/action/send
Configuration template: /api_key/{api_key}/contacts/{recipient}/senderId/{senderId}/message/{message}

Then I added api_key and senderId under key value pairs.

However when I try to via post via the api like /sms/outbound?message=text&recipient=26097xxxxxxx
I am getting error 500, Internal Server Error.

Where am I messing up.

Will greately appreciate your help.

DHIS2 version: 2.39.2.1

Gassim · 18 September 2023 05:53

Hi @iammash

Since it responds with a server error, would you please share the complete Catalina.out logs (without authentication/sensitive info)?

Thanks!

iammash · 19 September 2023 14:06

@Gassim thanks. I don’t have access to Calalina logs on the server i was trying this on. Let me set up a local instance and then I will share.

moses_mwale · 8 August 2025 09:32

@Gassim this will give this error message with the exact configuration find the log as requested

USE GET - checked

ERROR 2025-08-08T09:23:11,909 Server error 500 Internal Server Error: "{“message”:"Error: Invalid Contacts. Please ensure multiple contacts are comma separated & inside [ - ] ",“errors”:{“responseText”:"Error: Invalid Contacts. Please ensure multiple contacts are comma separated & inside [ - ] “}}” (SimplisticHttpGetGateWay.java [SimpleAsyncTaskExecutor-288475])

The recipient in this case is a single number but yet that error.

The SMS is suppose to be sent out at program completion for my test case

Gassim · 14 August 2025 14:50

Hi @moses_mwale

Sorry for the delay. Does this also happen when using Capture app?

The error seems to point at how the contacts are configured, so how’s this recipient configured? If it’s a single number, maybe it needs to be inside [ - ] “}}”?

moses_mwale · 15 August 2025 07:02

Hi @Gassim,

I resolved this case @iammash . For anyone using the Zamtel API in a Zambian setup, I found a working solution.

Initially, I couldn’t really see what was being sent out to understand what was happening. To determine this, I raised the debug level. In the dhis.conf, I included the following to log all outbound HTTP requests:

logging.level.org.hisp.dhis.sms.outbound = DEBUG
logging.level.org.springframework.web.client.RestTemplate = DEBUG

This helped me see the concatenation details, for example:

DEBUG 2025-08-15T06:35:54,658 HTTP GET https://bulksms.zamtel.co.zm/api/v2.1/action/send?api_key=YourAPIKEY&contacts=097931xxxx&senderId=MOH&message=Dear+Moses+Mwale+%252C+Your+second+dose+of+the+Hepatitis+B+vaccine+is+due+on+2025-07-31.+Please+visit+your+vaccination+facility (CompositeLog.java [SimpleAsyncTaskExecutor-30407])

DEBUG 2025-08-15T06:35:54,658 Accept=[text/plain, application/xml, text/xml, application/json, application/+xml, application/+json, /] (CompositeLog.java [SimpleAsyncTaskExecutor-30407])

DEBUG 2025-08-15T06:35:54,659 Writing [api_key=YourAPIKEY&contacts=097931xxxx&senderId=MOH&message=Dear+Moses+Mwale+%2C+Your+second+dose+of+the+Hepatitis+B+vaccine+is+due+on+2025-07-31.+Please+visit+your+vaccination+facility] as “application/json” (CompositeLog.java [SimpleAsyncTaskExecutor-30407])

DEBUG 2025-08-15T06:35:54,705 Response 200 OK (CompositeLog.java [SimpleAsyncTaskExecutor-30407])

That level of detail helps you pinpoint issues in the request.

In my case, I discovered that instead of using recipients, I had mistakenly written recipient. Correcting this fixed the error.

Below is my complete configuration that works

I know it can work in various ways, but I couldn’t figure out why the SMS was not being sent using the senderId only the number (e.g., +388) was appearing. I didn’t take enough time to troubleshoot the problem, but when I do, I will figure it out.

I hope this will be helpful to someone out there.

Regards.
Moses

iammash · 15 August 2025 11:36

Thanks @moses_mwale

This is very helpful. Named to set it up. I will try to resolve the sendid issue also. But if you do, please do update us.

Gassim · 6 October 2025 08:36

Hi @Dwellon

Welcome to the DHIS2 Community, and thank you for sharing with the community. This could come in handy for other community members.