{"id":16415482,"url":"https://github.com/fuadop/sendchamp-simulator","last_synced_at":"2025-10-26T19:31:56.743Z","repository":{"id":36974224,"uuid":"497279811","full_name":"fuadop/sendchamp-simulator","owner":"fuadop","description":"Local simulator / mock+proxy api for api.sendchamp.com.","archived":false,"fork":false,"pushed_at":"2023-02-12T11:35:12.000Z","size":2616,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-31T23:05:12.966Z","etag":null,"topics":["email","emulation","interceptor","interceptors","otp","phone","phone-number","proxy","sdk","sendchamp","simulator","simulators","sms","ussd","verification","voice"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/sendchamp-simulator","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fuadop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-05-28T10:03:44.000Z","updated_at":"2024-04-13T08:51:33.000Z","dependencies_parsed_at":"2023-02-16T16:00:44.980Z","dependency_job_id":null,"html_url":"https://github.com/fuadop/sendchamp-simulator","commit_stats":{"total_commits":23,"total_committers":4,"mean_commits":5.75,"dds":0.3913043478260869,"last_synced_commit":"caa990b5c02206cfac0bf5994d1f5a88fbca7dce"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuadop%2Fsendchamp-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuadop%2Fsendchamp-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuadop%2Fsendchamp-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuadop%2Fsendchamp-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fuadop","download_url":"https://codeload.github.com/fuadop/sendchamp-simulator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238394323,"owners_count":19464583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","emulation","interceptor","interceptors","otp","phone","phone-number","proxy","sdk","sendchamp","simulator","simulators","sms","ussd","verification","voice"],"created_at":"2024-10-11T07:05:55.804Z","updated_at":"2025-10-26T19:31:55.366Z","avatar_url":"https://github.com/fuadop.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sendchamp Local simulator\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nRun a sendchamp simulator locally, to test your apps using sendchamp API without having to spend a dime, you can also write your unit tests with this tool.\n\n## Table of contents\n\n- [Quick start](#quick-start)\n- [Setup](#setup)\n- [Usage(Lets gooo) 😅](#lets-gooo)\n- [Examples](#examples)\n- [Timeline](#timeline)\n- [Contributing](#contributing)\n\n## Quick start\n\n![summary](/assets/summary.gif)\n\n## Setup\n\n**CLI Tool**\n\u003cbr /\u003e\nMake sure you already have NodeJS + NPM installed. To run `sendchamp-simulator`, it's as simple as doing an `npx` which means running the latest version available on npmjs.com.\n\n```bash\nnpx sendchamp-simulator --phone=2349153207998\n```\n\nAs seen in the above command, you need to specify a number for the simulator to receive text messages on. That doesn't mean you cannot run multiple simulators with different numbers. Of course you can !\n\n\u003cbr /\u003e\n\n```bash\n[5/27/2022, 11:59:40 PM] Simulator started on http://localhost:2920/?phone=2349153207998\n```\n\n☝️ You'll see a similar url printed on your console after running the command from before.\n\n\u003cbr /\u003e\n\nSo you have another number right ? Create a new browser tab copy and paste this url there, and you get a simulator for this number. Create a new tab again 🙃. Paste the url again, but this time replace the phone number in the url.\n\n\u003cbr /\u003e\n\nFor example: You want to run a simulator for both numbers **2348123775374** and **2349153207998**.\nAfter starting the simulator: Go to your browser and open two tabs with the urls:\n\n- http://localhost:2920/?phone=2348123775374\n- http://localhost:2920/?phone=2349153207998\n\n👏 Yes !. You now have two simulators ready to receive messages.\n\n![simulators](/assets/simulators.png)\n\nYou see that green dot at the top right edge of the simulator ? If it's not green means your simulator isn't connected. Either you need to reload the page or restart your simulator ! Please don't use old browsers like Internet Explorer for this simulator or I would come for you 😠.\n\n\u003cbr /\u003e\n\n## Lets gooo\n\nNow that we have the simulator setup, It's time for us to start developing our app using the sendchamp api. I said sendchamp api right 🤔. Not really. This simulator is more like a proxy to the sendchamp API and intercepts endpoints like the /sms/send, /verification/create , etc. So you won't have to spend a dime when testing your sendchamp integrated apps.\n\n\u003cbr /\u003e\n\nIdeally you would have a constant holding the sendchamp api base url before making api calls in your app. So you can dynamically change this url based on your app environment. Let's see what I am talking about below.\n\n\u003cbr /\u003e\n\n## Examples\n\nPardon me 🙏, I only know how to write nodejs and golang fluently.\n\n**Nodejs with axios**\n\n```javascript\n// use simulator url if in dev mode and live url in production\nconst axios = require(\"axios\");\n\nconst BASE_URL =\n\tprocess.env.NODE_ENV === \"development\"\n\t\t? \"http://localhost:2920\"\n\t\t: \"https://api.sendchamp.com\";\n\n// Now lets start attacking the endpoints.\n// Lets send a text message to one of our simulators phone number.\n\nlet options = {\n\tto: \"2349153207998\",\n\tmessage: \"Pinging my simulator\",\n\tsender_name: \"Sendchamp\",\n\troute: \"dnd\",\n};\n\naxios\n\t.post(\"/api/v1/sms/send\", options, {\n\t\tbaseURL: BASE_URL,\n\t\theaders: {\n\t\t\t// this doesn't neccessarily need to be a valid key.. anything works 😜. but if you want to use other endpoints like /wallet/wallet_balance you need to put a valid sendchamp public key, since those endpoints aren't intercepted and they go directly to api.sendchamp.com.\n\t\t\tAuthorization: \"Bearer \u003csendchamp_key\u003e\",\n\t\t\tAccept: \"application/json\",\n\t\t\t\"Content-Type\": \"application/json\",\n\t\t},\n\t})\n\t.then((response) =\u003e {\n\t\t// exactly as sendchamp would respond you 😉\n\t\tconsole.log(response);\n\t})\n\t.catch((error) =\u003e {\n\t\tconsole.error(error);\n\t});\n```\n\nNow, let's check the simulator !.\n\n![result](/assets/sms-send.png)\n\nAnd also in the console, we get the regular sendchamp response.\n\n![console](/assets/console.png)\n\n**Nodejs with [sendchamp-sdk](https://github.com/fuadop/sendchamp-sdk)**\n\n```javascript\nconst Sendchamp = require(\"sendchamp-sdk\");\n\nconst sendchamp = new Sendchamp({\n\tpublicKey: \"sk_test_$lkdl$lksd...\",\n\tmode: \"local-simulator\",\n});\n\nconst sms = sendchamp.SMS;\n\nconst options = {\n\tsender_name: \"sendchamp.sdk\",\n\tto: \"2349153207998\",\n\tmessage: \"test from sendchamp-sdk\",\n\troute: \"dnd\",\n};\n\nsms\n\t.send(options)\n\t.then((res) =\u003e {\n\t\tconsole.log(res);\n\t})\n\t.catch((err) =\u003e {\n\t\tconsole.log(err);\n\t});\n```\n\n![sendchamp-sdk](/assets/js-sdk.png)\n![sendchamp-sdk response](/assets/js-sdk-res.png)\n\n**Golang with [sendchamp go sdk](https://github.com/fuadop/sendchamp)**\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/fuadop/sendchamp\"\n)\n\nvar publicKey string = \"your-public-key\"\n\nvar mode string = sendchamp.ModeLocalSimulator\n\nfunc main() {\n\tclient := sendchamp.NewClient(publicKey, mode)\n\tsender := \"sendchamp\"\n\tto := []string{\"2349153207998\"}\n\tmessage := \"my sms message\"\n\troute := sendchamp.RouteInternational\n\n\tres, err := client.NewSms().Send(sender, to, message, route)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Println(res)\n}\n```\n\n![go-sdk](/assets/go-sdk.png)\n\n**Golang with net/http**\n\n```go\npackage main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"log\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\n\turl := \"https://api.sendchamp.com/api/v1/sms/send\"\n\n\tif env := os.Getenv(\"GO_ENV\"); env == \"development\" {\n\t\turl = \"http://localhost:2920/api/v1/sms/send\"\n\t}\n\n\ttype SendSMSPayload struct {\n\t\tTo         []string `json:\"to\"`\n\t\tMessage    string   `json:\"message\"`\n\t\tSenderName string   `json:\"sender_name\"`\n\t\tRoute      string   `json:\"route\"`\n\t}\n\n\tsp := SendSMSPayload{\n\t\tTo:         []string{\"2349153207998\"},\n\t\tMessage:    \"Lorem ipsum d, no lele\",\n\t\tSenderName: \"Dash\",\n\t\tRoute:      \"non_dnd\",\n\t}\n\n\tj, _ := json.Marshal(sp)\n\tpayload := bytes.NewReader(j)\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"Accept\", \"application/json\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\treq.Header.Add(\"Authorization\", \"Bearer ACCESS_KEY\")\n\n\tres, e := http.DefaultClient.Do(req)\n\n\tif e != nil {\n\t\tlog.Fatal(e)\n\t}\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n}\n```\n\n![go-http](/assets/go-http.png)\n\n## Notes\n\nThe following endpoints communicate with the simulator:\n\n- \"/api/v1/sms/send\"\n- \"/api/v1/verification/create\"\n\nYes, sms OTPs would get received by the emulator and you can use the \"/api/v1/verification/confirm\" endpoint to verify it.\nIf the channel set in the \"/api/v1/verification/create\" body is not \"sms\" the request is processed by \"api.sendchamp.com\".\n\n\u003cbr /\u003e\n\nAll other endpoints not listed above are all processed by \"api.sendchamp.com\". Your local simulator is a proxy ✅.\n\n## Timeline\n\nCurrently the simulator works for all sms based requests. I am looking into also intercept the voice based requests to the simulator, if that would be necessary.\n\u003cbr /\u003e\nIf you find any bugs or have a feature request, please file an issue on the [issue tracker](https://github.com/fuadop/sendchamp-simulator/issues), I'll be happy to help!.\n\n## Contributing\n\nPRs are greatly appreciated, help us build this hugely needed tool so anyone else can easily test their apps using sendchamp.\n\n1. Create a fork\n2. Create your feature branch: `git checkout -b my-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request 🚀\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://fuadolatunji.me\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/65264054?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eFuad Olatunji\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/fuadop/sendchamp-simulator/issues?q=author%3Afuadop\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/fuadop/sendchamp-simulator/commits?author=fuadop\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#infra-fuadop\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"#maintenance-fuadop\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e \u003ca href=\"#design-fuadop\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#example-fuadop\" title=\"Examples\"\u003e💡\u003c/a\u003e \u003ca href=\"#security-fuadop\" title=\"Security\"\u003e🛡️\u003c/a\u003e \u003ca href=\"#tool-fuadop\" title=\"Tools\"\u003e🔧\u003c/a\u003e \u003ca href=\"#userTesting-fuadop\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/sadiqful\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/39303081?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAliyu Abubakar\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#blog-sadiqful\" title=\"Blogposts\"\u003e📝\u003c/a\u003e \u003ca href=\"#business-sadiqful\" title=\"Business development\"\u003e💼\u003c/a\u003e \u003ca href=\"#content-sadiqful\" title=\"Content\"\u003e🖋\u003c/a\u003e \u003ca href=\"#financial-sadiqful\" title=\"Financial\"\u003e💵\u003c/a\u003e \u003ca href=\"#ideas-sadiqful\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#mentoring-sadiqful\" title=\"Mentoring\"\u003e🧑‍🏫\u003c/a\u003e \u003ca href=\"#platform-sadiqful\" title=\"Packaging/porting to new platform\"\u003e📦\u003c/a\u003e \u003ca href=\"#question-sadiqful\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e \u003ca href=\"#tutorial-sadiqful\" title=\"Tutorials\"\u003e✅\u003c/a\u003e \u003ca href=\"#talk-sadiqful\" title=\"Talks\"\u003e📢\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuadop%2Fsendchamp-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffuadop%2Fsendchamp-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuadop%2Fsendchamp-simulator/lists"}