From 8c58cf0c363e5cc64bb6995decc5e84481379327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Fri, 19 Sep 2025 15:17:40 +0200 Subject: [PATCH 1/8] feat: remove unused hooks From ed349197dd5abb9be98692efe3a0193de5fd4672 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Fri, 14 Nov 2025 23:44:24 +0100 Subject: [PATCH 2/8] feat: zulip addon --- forms-bridge/addons/zulip/assets/logo.png | Bin 0 -> 15218 bytes .../addons/zulip/class-zulip-addon.php | 102 + .../addons/zulip/class-zulip-form-bridge.php | 17 + forms-bridge/addons/zulip/data/openapi.json | 23894 ++++++++++++++++ forms-bridge/addons/zulip/hooks.php | 99 + .../addons/zulip/templates/support.php | 128 + 6 files changed, 24240 insertions(+) create mode 100644 forms-bridge/addons/zulip/assets/logo.png create mode 100644 forms-bridge/addons/zulip/class-zulip-addon.php create mode 100644 forms-bridge/addons/zulip/class-zulip-form-bridge.php create mode 100644 forms-bridge/addons/zulip/data/openapi.json create mode 100644 forms-bridge/addons/zulip/hooks.php create mode 100644 forms-bridge/addons/zulip/templates/support.php diff --git a/forms-bridge/addons/zulip/assets/logo.png b/forms-bridge/addons/zulip/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..f18e04b8630d51040961ddf5ca1d6521f04b2cdd GIT binary patch literal 15218 zcmeIZWmFu^7A`!vy9Wp!90u3HouI*efWch{cS{Ha3BetLySoHWkl^kf9D>6o@A38B zKWDA){yVc)cUM>K{p`J;+Ev|MwI)hcSr!BJ6)FG#z>t@dQh&Jy{yC5lU(UTE;1K|T z@RPTOj+;8zlhVn>(ZbpeLh0t^1fhgLtt|im=t4p2t~*(4QrI)idlZhm`0i8z9P?cRHz8?c3i}F_V^6{J4sF$H+_}+I(WnXIxA0Xe)Pv zyY+DPxH$V!an*7={An`7%Nqvj(StPu8trkkEpAEO#bcNwKa!}md>2}WeHPhoxcE-s1ar?yB{6~Au zj$As{CDz0VzQx)! z2q9iCoAnQ#ezGh4RnKbB^k#9m;Su9wzSl2?Nq5+;Ij2FYDo>Bs$M7=%cY7|-Z0wNt zK+JYkSbUv>)(`4UqmID%hO+7z^kwJR>82)(qmAfkUjs|AdH-|?jiELgCmLyK*CX6F z>mSPK=cdKD zao@c#s>Pkfp2)K+<;SyH2t~OhQy!g9v_+adwzpGz zbno)W0Vu|@wE>fZHqdz^Z;@H z0^|G(X}(dO_Y%Zs8&y^H+4 z2IIWMLW6HRd-&&Wz8{YbPpT2Y-#e^E;Q#{=l5T%Flw@%7_YENjvwMFPp-}919bE zxJZ)|2HEpG>~$_(mHCPWD4@`801yNy6~{>A#bAQa4EgE?dg_FRh8JEU(+;KtvhT_y z<5dG=^a;y?;)*9f*i|Vchji(6Wnr4m2#B%IC=6l;xA+EcFrFZ51uvQ5Jh?7ltflAS#`9gq%mN` zG{_I-6XU4aeNIK-GP-jhVXd19D>9&B^!jhrA_8AwM{N;mX=qFix#A6c}8U!5N^bfa%{B8uyn{EN0Rtwe6T@A1ByyKk>mrL*ta z;1X8TFZqh>)N65Zectg`fxQz(;|OSv2b?%fX0RI8hJLbqWBxBw;lE%HHLnr?UIlN>RO=_HC#x2Ds(H+JE0ideA#&XwR?6s2wBeZYpw}0& zE^BUbjb^+*MJhEtxF>vdUapkT4^ckWT2J%PKS8)d`PvXIgE>Tg zhmGg*M5pS%%J&_Ue>Wk6t)!uonYfU^Cq+jZo{NTtvHV5;PWv~%`!_=X5<@^D-ViHh zYp|yJl>|&SA%99Y`axbW<=PfM^R#k3J-PJ*W&zyr7_~2JS4g6G((5e>o=*zWvGmzB z-F}mwXa;SmXT`;CWO0ExP7;~DK8?=c7*?J#;w>|r^NhLm{)b?wP^+bx9GWE63B^!Z z=g9iK&*eB<+s8M@4A{oeoC(V^&r_jP%WkhnV9JYI=ro*Jyp-_K-Ra#A6$k~VSIn4?xNURh&*PTxd%3=<05Vfn@Y6Vj<>G3SAbcmmJ%(IAuC zwYcC6+XdO5jb4V+LIdU$eheRVxo=Ww`8Dw87+w?U{H`U8cHY<}aHk&aq+r?8AttPv z+$dzI4W`xYywG*rJxS`@NDv)+rO2lYF9dE?Boj-NM7R>dKKU<8uFOTpxcQnmsKQ}6 zl>O2cv)7v(GMl+3`z+(Iw+RHMefhW=m>&#z87JGd?LF8zDgyQt2j+9O{AOnRUkxSS%teZUF}r9 zg4NV|udJXp^D9g9;358?Jws0ZLxtMK;(4DPF1LE{8^TvX3EJjBgyEL<6?Pf8nJ+N& zFdL-e5)xZGS!Zf#Z z(3*QYxcK~9YrsIwcb{TUyWZ;vUpnR?WkUGz9{$Rw2mMEaCN`RVfB(X{PW-!h{BjNQ z^Gm>lKr5}%ZiMlNZ1bWIg?(b=Qomd>O|~Ng&O*v?m~b}|U9lDV!x!ckB4QAK{{D=- zMd`w5f+R?KG8A@-sq8At;?Uz!z%X*0?a}1HWB0104D3m6exX3uxO$vndC{m#)O1+I zi@b8(q=wg(XA^dEd0Hyb$*hVCx2Bzoipx`0I9j+Tu2J4eCh{(jQcZLER+^2n-sd-P zM48w|)P+3w7@aN5U}YxC)Boz-4yk0HLGnmQN{>fPMkrYnEDa0WZP%75fBdBQVq$jo z0M}1;cB)Mf9_)BBHZW+@9n;lKS+(y@CxlRwZ%}#Y3Em-wfVb0Izo6iIopLheR5H;i ztng5Iy=XMM7?0DUd1d4K@m%gbRRwg>`k|=Na>mb17zZKL?oz>BU02H}d!M4FqU4O8 z2Ps|n_%du9$pX+jVmaZ>~rR#G$tX z&|nLp6uGg$@Pwmsfv4qmet&H$0t8%$Y0B+=fOJRgdR)FaWg{E zj=S|65y61BM2SBt4TN;&1S2b$(J9lo(tagMi5h;yq#x=1K%}NFFLA40JlZqw4CI8X zq*M33%}Q_mii{?WlY8QQ&g!RPiy9aIKKm81D=sDr+*G7^k>F5&Rp^3E%@V3RTUn;! z=$AvFHp+dErsC7p5|cDV&b4qyC-u9lZ#Am}^V6)cpDd#DM51&iLjjeNeX5>X-V}-Z zQEXkdrP5n|zzugt`gcNv4Ycs2G*=1c!g?oSfSejZ;=SbKpoULl3oxo~c{Fc$c@-Dn zfM^^2mvShaI}LTTaQll~$G*`zOX#6_Ksq=^61Nb33Nqf*ruH{7kAOG37j2$ey!TnV z2!`LeSY6;1Bs%R{(q|-wx#d%e6P$dcdtE>2K)^w7rM-xNk=Jm^v_*#6>%vKf!%^=3 zMmvUEwSL1nJ8~nVN(p-ceX;H&_H)C(vqKBN^zsLbwiB zhn8gClqKdp%+F6x`e00c)>OibmbRkg;JSDfvYAEvKo=^BbC(*lC3EzQEahZ%2#|D!I z;W~@%|5_0VDL?^xfu8k$a-LjqmnF?*3j-H6M971|fXon1?ozuFMnl<*Fy8&X#jvf~ z_19{}DWF8GNl9~kf1IeP-%@)V0*%&D7Rwxa@HwV2>ud3V1qry*PRD~$PlO%b(zVhz zxF;56`&hGjwVRPtQ3a@4*jJEH9F7uGp-u=~)1%a`l)3xU{&WG?yx zOx)X+n^~QF#ue`0u?FI`K@-D_0>WrnrO*wKafLqXZ7 z{dxF7O`A!sE4cW5f!;!771MBm@SxjI<{Gs1%HHn~#betHx&_%tnurl!JF4N}=Y5uo z0(g5kfXVf~JrFf=Lh*Y}1-X5G>6CFjzthxfsnY0zO#|4iQf~Q_!Au@lF-?rBiy$zU zTwA^I_80kl_$fNUFWacPn*Jv*iWt)VFroNeu@6M9}k7s*h zA)r=j2(r;nREekCUMz*TW0s#NlAh%)L?t_e;qtLqgJp1(@wPY(nYBK5;Z z2;gac?A|2sL#UdS)MA;dIunJ|&Gsf7a1PtjQB zpEwgp{xYVQp|+{h-M^$@vg-ZB9V|J=L%%SUCmS*!4C3>!91XIbA!+$lR~I%}O#eOh zUY1j;t9I|#;0m7i^stUjBd%^I-;G*s#3L2Imni*w%I}9wq`FG+old`*QppBhyFD}; z*z->Vbx7XDJ|OMaupVSX2yfR=zhjjikRj`Tpb9ebK_3z~F-5ERRs7={!@Hq4&s`59 ziQ1(x^uV1&1Zs(oq3UPZ=NHjYVuAHWvGPs!28nMcA_`Ky*nRuowui-8;RM1PcD29= z)_qAE=s#b|9U7S0{37>Stv8?h^*r|-6kai}vchWmU1s1cmRZYiZg0HC;_G)|Z3wp5 zxL;L0zp`fd?9<2#W(3x7WYup@Ht`wVjbHg(=1`ko*^E7eX2V%ANa$C(52-&^hsj{yfs@B&yJIY@`Obu8nVN8sPn(E>QC{%!k z;C|5utntA}gIsXMIO2)@pjK|#{?b|78)l&A_TN&GSNomG{y?%>AZRvS5kL_Tt9IBepK(*CIDQ z43aSgY?-=upbFA?7qg=CGsG+(3T~HJP01O!-(?(k!xXBQqluKD*qJRa8Nac?&_qb~pi?H;#D93O#)KS9 zK^dd0{GLsH<2hd912I<2{n_!#<}vx2qeilghZ3N~f@I%ZVsJ+*Y>n9)M}pWaQt|uL zt`rBt*qJ*Ph4G20@W}mAR-VdG8u}^9x7xRSEE^ab`$~$tZ7O77I(aG)`qzAW!QWyH zz8Ly%8o14kanZ=U0jZEt5xys9@dPrHFrDE$YpC%IUt1b#@jE(eG4sr{&3GCu>DyV;)Mg(5Sd$*TM#|A#xuWhuH5BYR$V*+pT z6~njWU{aqXV4$LTj>9l;jbdY|i~6<{U$Ml(TNIW7ND*CDaW%7`74m~$N2^@rPyT=m z1(zmSlUn$fO@vq0FPjBAN^b?t9PQb_=8mQiHmJSR%Vq)qAS?=X0-M=F+$c>Umevj+ z>XX(^YD#N!5Vbas5>UxW5@Ka7=j{S{=dG+^=51>xU`{P6f+`FZd;zeBxPd95_I3`g zf>03kU$}xVfJb(B;oB^_NLl-z9GY(Q3NsI>_AR-PEOVr307Ax2RAU3)xnkK55(Uv zq#&+lF4j(N){YL8e=xzOj_z(CYU-DE%76H0@1&&kPk0B{zq9bd2Rjt(#LmG6WVg3x z|91^nH))R-kiR?hf7Ni+c-eDdSBJPdy1SS`q&*-GZZ!W6VQ%(MeJ6JpyT8IQH)Ds` zLF`{dU0>-yL~T|0nK$ zNdF`Dzl2|;l#~Re9L?PSxF;_KqW)uF(A?3?+FbCjq6L?!IS|4RVdduGd^wr%nzIUU za9Xeed4c>ETwoxW!<_TqpyVA~-M|iJkUvl_;B3|}I6UTHFoZ{dht=E+XvWHI%FEAc zD!}~$!3hLHIQSrZ7JMB42BG3&{gRbnyMOoU50v=}l)0H1pBX zQwuIu0aFVwHy@8FFSiBXUr^>|f-;US_TZQ9w6+IZLfD-gEdOfwL%5*0syv9AlMVQ< z8dW>6o5hO)i2ALygFEzJ4I0+=kauq2KWuXF^709AaBy(}`2_g*IC%dhqy=$teaXZ> zm>fVhuD{{_=@!A4U|xs?|H;!AfWI_eViA;dfq>l{T{IjW?LgFjT%!D=`B!>V3jeKB zcYhlKcGiD2QBwYuwt`@@zZr1_dqB+pGW4SNwAtEfBNES1^L4h@MUasaIgaTH8{8gxj6+nfXqM+ zK_HNt{qF&@{~6W)h*+5Y|HFy!UjqL&4ZP_6t?p%dd6}))|2bX#owGkQ{y+Tvy)XVB zT6lr}pOOEH-~Z9|Kf3-a2L3DI|7F+z==!f1_^*WjmtFtA(S`c24<3la%Uh7=%jXP8 zk52aGQwY&iQC12-3Sa=R!QUhKywspL$?3WR0BCrB4j4dcI`K;-lAFAeG|~cJ+$|~C?)9IqjK7@R&k(-ONpG*%+1BhKCFmK# zKFeh2oqt9Dp4W`v3)SMLSoh0X#ZNHFw^>^$vRJ3VE_9S6x@79eKmfAbqYr#2`7Sl` zO=s&B-<4}a1!-_1nR#*W*79A1h!p-_wF%|>a3u|ba${{xjbe%?_x5MOgMj|gL;bAM z_q$A)<@^mB-tR%g1-S~0W(g;l2{<}vq%3bFzLO~cKbLbh>f|S*s|iiZ9x;!-zhH2G zlXVH#;V1vG05+~fvW9DTqJX;6+~z^Au)jE3DXUy35QR7}r^5vu=Imi2&i>pGF->GK zNA9lZrh+vCw0#=$z;@R+Y*`13v&g+ZG0@52uG^q|4lNzpm zTf_D6WOL#}_Qet%-KB55WkVOKLe42NaUNfGQSZEXeiGc3V0H>5?2he>2p=(W#5NQJ z%$Oo)!hD7U7s@6)ltWH4@IWnhpDi)2-@$Z|YPXGF7DgA8KFr$%t&X+2wY;C#k`4(1 z7!77S(T;k`ynDERYEph!L6f0htDJ++ z`^;E~-Ec3i-y8YnbU7+pZi|*_2yE0db~2iVgHmVdilydjUiPuCnt=t;%}{*+r`v> zUiGEasc?ZZF+Y2Y(2x0FfMypO(V(00%#EC!O$J+)Z(PrLWTWaL>a5{<7tRtp1h99F zG2b*lPIFPjAc=ef%%gG)YO_J&}ondCBhhq?h>PUc^z0N zKRFaIW!Zjl(a%-RZpS%JKlttcY@#4~)6O*mN|3+42`>oFuhG0ss4o%Dc~5n8X6vo? z$?aoMU+zQk(NGo~X=_WM<5LeW`4_Vb>07ulni`(3^CGFwr@}oWbhkuFdy|z}u4RTW zRXV_p+f-kklkw76lhh{GZquM##a(aRr#+AGZxMjg4@2?a-X0BU+>+ZP`In=>(zU7Y zG^&Dbu1}Ia`j`eTS~J^4cGPKo?zLZCZDILTEMHlA9#)X+j#gyH)wR_kwR6#5T7m0; zrDBmp;1(Vxx4JJIno{SfX>3T^xpmOkgj77pFI1>$rjqI2_p3{yrb=x~In` z7+f-6_?%<`m@oS2$-+30;q;7aqW?t;SF4*hv!W@q9yGLiM~Ph)Y@g|(>5n-#V}mlH zC7|rnv+In*WxNTU|BVM2skWt}!55_-FMJ*lli~oG*QuA^0jf#~n8_3{QHbjdyUYRs z(W$m%EJW|Y09zVk6uRD@rAJX&0|k^OkyOjhjIw~T&?$*Rup4q@9m!htTA;7ehDu>1 zoDLky$I+QccmcR^tPJ>6Q%`>s3w&g%ks4FLOm~H#9r>OZ!W-y!N-AZ>d>urLB)=*Ma2?anQ(1FvT+X^Y#qgR#4tslM=B^Q4n#8+DP zdzZnhof=iA;67wnm!io_lC>`vMuUeE!EOW| zaves5fe;iq?eCW%U86v)SF{YCe8dp}-moG85_{2nj`;-DCU#=Pd!cah+eisOV`NO& z9x4u)vY1FP1a{-3HSe^K&l_w`Edlt5x_U#IM*%wj@B4ROGa~*&Tr)e^7 zU<#AsT8ck(U+0h^K+zNob$-k5huwoHo=lQh1xW_T2;1o30uCwUx@seGI%|0nPBLkQ zJ&D8P@9j9wt!o2s!bF(~cvy${8j$l*X~>=Is_HFiVla_uGKLM3!grPyL0u{KF9K`jPezOjBU{EYXLtzEveN;-tZ zllAM<`|Q5D*0~WXB|!e-N=9whs37UEW0k8 z&SJM59FDGgwuYZ@qEW@|*y3pvQM*2#RTIIMZB-o7tgZdF4{90$!&ESryg79{&C~rW+MI-0i1?bflRZlK*F^11TwGRe3e}39+qB_r z>8cFDM?Pp9og6ygDZA|R+R@=@H}{r8dCr3=LcitO0A7^=vfOE70t_q;oDq_+AB-s;S%iS6a@HUe(EZ{K*v~SJhapAU~ttU zk~mHI*G9OO_~I?rDH|;6$@jS2|$QJ_BmBRSmlw*kE7=!rnGJ_oYp+$@RY$(cNZbvF}>c zPV}_MR>dGbI@y6m7NcSqGzE0Jz=wNN{0cU}Ixg#pWn=724|$Kb*0lY^4J<+*w>q0L zPVzUE+kD|m3@7J==-%@Yp%&Q^|x?3!x}>5jLvvmSG*cptZy71lPhr|#9WBOZ@0u&SPX zQP`G4DU7rn3eqZ-&*qu|DpUk#*F-x^SpF;atDfsuZf7( z7|9Mojma-cT`em`iBEE!ys-|AN4k6xh8OXww9uVW8y$(phpn^kh68emIv&u`DX>>M z*M)A{VR;;}Rx43Q(oRP;w=+mTm2*3*WOS7y-QdGDk6rbaj-jZ;^pw*z@qfiqp1{u} z4UCdg-E{=>kaK?2vR%3-a;ZAoz-~Bo#H)IyP9mn3A^i^c*%3aOGNm=v7 zJ6qnj>xm3D{G6`f5ySXV7A`UNxCA?3R z=Q4Y&u*gK=Gf)C>2DZ}A^PC|r#jnX46z~ej)9@MVB-?Q@50}%ue+kaqHC>Ak^(-u%?S=aj#GpvhHQSLcfH#?31k;$P4`mYJ8HVN zyeJ*+n@1WDC^?-1ch`iv&L(CVXll8*Z#P1te1$OVc(ZK{yL*>U3oOGX2f{}0J&0Bv zA8Q77iMwPlSJG73#u!QaW{%T*V$rbejh;n407f9zbU`LsQwodlFdm3+;p^MO6*q>i zTivTPO9ubhUxW=08FRcMqBH3nT|*(Ki|nXl?8sPE@^J*mXT~%g}>GE}> zduJ?5*M&xi!Io;62D*_5G&<`_i)k3WCwWR z-lSYLF-Y^dHSu8ztjS`Z?hVDp1;a{v){Sn?(Rzx_B$%o@J9*Igg&BP5=DRYrGetin zkM>>)8?+VM5e6f`xAP%ih7@GC0VUvLFuT5tA=77JZ%o97|B{L}JcP}v|M(H=WR4tz z*{w40dA|Vg@obcP{9>H4oz>h9@HDU3bEZc1^Ba2&560epsJVe$|N0Nl&qHAV!r+FQ zz;M2Db>f5YRj4w*v-vfw3YP*u{D4fT3jr#@_NaFiZ_JIjNysi7egM_LyS&q>KMyva zPfGk=Qcbn!X#xcrwsyi*wYXMI4(*uZCWkMx)z_FixB2(DAMVCHtG=F9cRlI`%F^if z%{W?Bk%sHH>EEb|lKmpE_)>ocvp!0^=C9#9bB%*0ZmfN%_pD5~cM>iIkNUYk=GKsC zji(7Y|0&SzYpRL%5sgX9X#R8CM~kIabk!^jyDf~cx2b~L_YAlwx8mTuNw)S%{H5{H z>5}qQdZ?oCSS2B^+joRaFH=i$F;abWChZ(mZ()Ec%e@laD*-rLWHNz0`X`xQW5eK1 zds~{#*>QbcgV}&liRSJLSk!e@Kg&x{v5E@ppUyg=={MxFToGF`+hQ+il ze272|H54(hsWo}w4t}My8H{Ff<~zb!*h$7EPZ*xoGf6hsd02xqEy5)ImzOSEC-;Su z@YkVkv(68yQ%p$@!eX$1;S>a@qe0X_=*sbon*ST5-Tu$Ti~fk?PLF7MwT47pO!%M( zKwGuqsrI-*vIaVwk-rhK@c33ARoFBJ^d$HENwYu$V=xyxOmF%E#)SAFGFyDG7oqch zrg=m`uvFMpf|!&*P^gPLjbYaFv9Fk`@iQ}D;-Rbm9T6>yc8NP8zew(AhEkmlM*n+) z?vqZ>?KdnHOd$yhDqlNUzSpEuPP;y&_FHJ_t^|H8>r_?^?t9ykQeAq*J>H<{T+q!G zd>tZYs592({fb2qCE`JoH>lBnjQx^-bQ!>B)oB0f)5szL;BY2GeHx>*{8gI~Sp9jx zJ?9ti0Pb_fNDrJ>0BjugaZn-_AW!GFjUgk`kE$?*)HSPM?@+;t8O{__k}elAva2>0 z8)z=KTG4b;><}O|(#jcqh0svE-?R8&G;dGML1qz!+idu?vj;L(x z)u!;$=|;w11rl%;6dKtZMfx1Ad$ACANgsKQaQgx-JzA%sb^Hlz9?kajr#g|$dYLE@ zWE6nk?)4)D}AzjJfQAY-!hA*s13(Q z;r008PB(BYovoesf1hVGk^wg9MZNSvv!lA|9f2ja?XuZ^b!#~>5Dhj0#qIB_?Z1sd zMcRz4W^}QQ=P}l*wu|zI@2Td%wig*t+SbPy547>-dC!q>9yfcdo53G%Mb4ue&?L&` zpVchE&fvR;;h#u-c$W}Oi;Jvo;z5BW-?toGYHT%qBo#SW3I%J_r5I=rYS7tgWvU0aW$tTiP_ zQXXvb79Q?cR#3dy@P&EU$^A|6Fr7MBqYMt^s;TMMJCasvu}s( zA=#+g{8&`Q@VR@Q`AcU<(okX>2xiS28#Aq5qo!0Cdg>%wo&^1AtAfo_o*b?v^lty; z$7uTFPTz;sb^-TIg)7NU*XOX$p9QovON-4NTN*vBzBSPF7A4z@E*M0BizXKhTbkN# zMprumj`hE=8QmDg7vq4pw&D7neMm3tBeH&>1dnc%EkbJxIKzm`%-P|kZh8~tY~dVtr4PU z?}rWB6N6U)wp0m2$GVI2wHw+DN$q;>?RJaJzS@@8zOu5S0A!EeP8~~mY)95{cv|@6XnPKc6ByC)_$|B z;(MaYZ9$ujKNSvNB|V;@8r4!|W-_HrTCk{Vizln%NU`~`fr#f*r$Ou85#OrMHE9AK zo~TiYMhWD1^Wb&f_q*o(9|h-k3mQ~ux=Tef=Lw+Y88@bs=whOSb72nnIFI$c$pUY2 z^4`;7^5PAMq{Bn(P}Iru3EHkP1qH?P=&zohdY zTvEoQGUb7!PtSbRk*k8n1nUl1j~Tn3u4?6-@VQ^s@Nl_OwuW|_zk#%WuH}*`Jf#58 zDStDH-bk+BG>?4U$x;|cr4JJm!_CbDoxEt?5LB&`JHp)~&y4>b@>7PEkWV5mGC2v7 zob!n|i7`CV4kH!+Lsi>SItW%HrxHt@+$3@}Oi9z(@XAgWH1K=LMswL^zBWO=Jjk$O zzCQO5zcxH>anPJ-mXI*X<+DPEM)8(H1IRczO(;uWCwUkKA^Th&|G5ZIb>Z5eLuG&@ z#q#+e^0kOB%g;DLva>p7vM5@KLK0pjF7rgiaGV(8a0rQMDs>@aa(LvgIdkoD3EstY z^lULEgb6G1u9iNll8Vx%iV`y)y>hQtQAJ1%wu?No?g}ySrQ0r^C7#D`H7{=63Y1R> zvRfqg?~3rR2UAW&JgN@5=I(4}DjmsdM%wF4m$I)j4r5#^E9NpH-aQ{UpWw#IGCfnc Y#-bi1mgRnbS;_^-ODjuNNSFlwA8jF{TL1t6 literal 0 HcmV?d00001 diff --git a/forms-bridge/addons/zulip/class-zulip-addon.php b/forms-bridge/addons/zulip/class-zulip-addon.php new file mode 100644 index 00000000..6a28464b --- /dev/null +++ b/forms-bridge/addons/zulip/class-zulip-addon.php @@ -0,0 +1,102 @@ + '__zulip-' . time(), + 'endpoint' => '/api/v1/users', + 'method' => 'GET', + 'backend' => $backend, + ), + 'zulip' + ); + + $response = $bridge->submit(); + return ! is_wp_error( $response ); + } + + /** + * Performs a GET request against the backend endpoint and retrive the response data. + * + * @param string $endpoint API endpoint. + * @param string $backend Backend name. + * + * @return array|WP_Error + */ + public function fetch( $endpoint, $backend ) { + $bridge = new Zulip_Form_Bridge( + array( + 'name' => '__zulip-' . time(), + 'endpoint' => $endpoint, + 'method' => 'GET', + 'backend' => $backend, + ), + 'zulip' + ); + + return $bridge->submit(); + } + + /** + * Performs an introspection of the backend endpoint and returns API fields. + * + * @param string $endpoint API endpoint. + * @param string $backend Backend name. + * + * @return array List of fields and content type of the endpoint. + */ + public function get_endpoint_schema( $endpoint, $backend ) { + $path = plugin_dir_path( __FILE__ ) . 'data/openapi.json'; + $openapi = OpenAPI::from( $path ); + return $openapi->params( $endpoint ) ?: array(); + } +} + +Zulip_Addon::setup(); diff --git a/forms-bridge/addons/zulip/class-zulip-form-bridge.php b/forms-bridge/addons/zulip/class-zulip-form-bridge.php new file mode 100644 index 00000000..804269b2 --- /dev/null +++ b/forms-bridge/addons/zulip/class-zulip-form-bridge.php @@ -0,0 +1,17 @@ +First message ...zulip.txt

", + "recipient_id": 23, + "timestamp": 1594825416, + "client": "test suite", + "subject": "test", + "topic_links": [], + "is_me_message": false, + "reactions": [], + "submessages": [], + "sender_full_name": "King Hamlet", + "sender_email": "user10@zulip.testserver", + "sender_realm_str": "zulip", + "display_recipient": "Denmark", + "type": "stream", + "stream_id": 1, + "avatar_url": null, + "content_type": "text/html" + }, + "flags": [], + "id": 1 + } + }, + { + "type": "object", + "description": "Event sent to a user's clients when the user completes the OAuth flow\nfor the [Zoom integration](/help/configure-call-provider). Clients need\nto know whether initiating Zoom OAuth is required before creating a Zoom\ncall.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["has_zoom_token"] + } + ] + }, + "value": { + "type": "boolean", + "description": "A boolean specifying whether the user has zoom\ntoken or not.\n" + } + }, + "additionalProperties": false, + "example": { + "type": "has_zoom_token", + "value": true, + "id": 0 + } + }, + { + "type": "object", + "description": "A simple event sent when the set of invitations changes.\nThis event is sent to organization administrators and the creator of\nthe changed invitation; this tells clients they need to refetch\ndata from `GET /invites` if they are displaying UI containing active\ninvitations.\n\n**Changes**: Before Zulip 8.0 (feature level 209), this event was\nonly sent to organization administrators.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["invites_changed"] + } + ] + } + }, + "additionalProperties": false, + "example": { + "type": "invites_changed", + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to all users in a Zulip organization when a new\nuser joins or when a guest user gains access to a user.\nProcessing this event is important to being able to display\nbasic details on other users given only their ID.\n\nIf the current user is a guest whose access to a newly created user\nis limited by a `can_access_all_users_group` policy, and the event\nqueue was registered with the `user_list_incomplete` client\ncapability, then the event queue will not receive an event for such\na new user. If a newly created user is inaccessible to the current\nuser via such a policy, but the client lacks `user_list_incomplete`\nclient capability, then this event will be delivered to the queue,\nwith an \"Unknown user\" object with the usual format but placeholder\ndata whose only variable content is the user ID.\n\n**Changes**: Before Zulip 8.0 (feature level 232), the\n`user_list_incomplete` client capability did not exist, and so all\nclients whose access to a new user was prevented by\n`can_access_all_users_group` policy would receive a fake \"Unknown\nuser\" event for such a user.\n\nStarting with Zulip 8.0 (feature level 228),\nthis event is also sent when a guest user gains access to\na user.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_user"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "person": { + "$ref": "#/components/schemas/User" + } + }, + "additionalProperties": false, + "example": { + "type": "realm_user", + "op": "add", + "person": { + "email": "foo@zulip.com", + "delivery_email": null, + "user_id": 38, + "avatar_version": 1, + "is_admin": false, + "is_owner": false, + "is_guest": false, + "role": 400, + "is_bot": false, + "full_name": "full name", + "timezone": "", + "is_active": true, + "date_joined": "2020-07-15T15:04:02.030833+00:00", + "avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1", + "profile_data": {} + }, + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to guest users when they lose access to a user.\n\n**Changes**: As of Zulip 8.0 (feature level 228), this event is no\nlonger deprecated.\n\nIn Zulip 8.0 (feature level 222), this event was deprecated and no\nlonger sent to clients. Prior to this feature level, it was sent to all\nusers in a Zulip organization when a user was deactivated.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_user"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "person": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of the deactivated user.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The ID of the deactivated user.\n" + }, + "full_name": { + "type": "string", + "deprecated": true, + "description": "The full name of the user.\n\n**Deprecated**: We expect to remove this field in the future.\n" + } + } + } + }, + "additionalProperties": false, + "example": { + "type": "realm_user", + "op": "remove", + "person": { + "user_id": 35, + "full_name": "Foo Bot" + }, + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to all users in an organization when a user comes back\nonline after being offline for a while.\n\nIn addition to handling these events, a client that wants to\nmaintain presence data must poll the [main presence\nendpoint](https://zulip.com/api/get-presence). Most updates to\npresence data, refreshing the timestamps of users who are already\nonline, do not appear in the event queue. This design is an\noptimization by allowing those updates to be batched up, because\nthere is no urgency in the information that an already-online user\nis still online.\n\nThese events are provided because when a user transitions from\noffline to online, that is information the client may want to show\npromptly in the UI to avoid showing a confusing state (for example,\nif the newly-online user sends a message or otherwise demonstrates\nthey're online).\n\nIf the client supports the `simplified_presence_events` [client\ncapability](/api/register-queue#parameter-client_capabilities),\nthese events will include the `presences` field, which provides the\nmodified user's presence data in the modern format. Clients are\nstrongly encouraged to implement this client capability, as legacy\nformat support will be removed in a future release.\n\nIf the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level\nsetting is set to `true`, then the event is only sent to users\nwho can access the user who came back online.\n\n**Changes**: Prior to Zulip 11.0 (feature level 419), the\n`simplified_presence_events` client capability did not exist.\nTherefore, all events were in the legacy format, and did not\ninclude the `presences` field.\n\nPrior to Zulip 8.0 (feature level 228), this event was sent to all\nusers in the organization.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["presence"] + } + ] + }, + "presences": { + "type": "object", + "description": "Only present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nA dictionary mapping user IDs to the presence data (modern\nformat) for the modified user(s). Clients should support\nupdating multiple users in a single event.\n\n**Changes**: New in Zulip 11.0 (feature level 419).\n", + "additionalProperties": { + "$ref": "#/components/schemas/ModernPresenceFormat" + } + }, + "user_id": { + "type": "integer", + "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe ID of the modified user.\n" + }, + "email": { + "type": "string", + "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe Zulip API email of the user.\n\n**Deprecated**: This field will be removed in a future\nrelease as it is redundant with the `user_id`.\n", + "deprecated": true + }, + "server_timestamp": { + "type": "number", + "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe timestamp of when the Zulip server received the user's\npresence as a UNIX timestamp.\n" + }, + "presence": { + "type": "object", + "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nObject containing the presence data (legacy format) of of the modified\nuser.\n", + "additionalProperties": { + "type": "object", + "description": "`{client_name}`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `\"website\"` as the server no longer stores which\nclient submitted presence updates.\n\nPreviously, the object key was the client's platform name, for\nexample `website` or `ZulipDesktop`.\n", + "additionalProperties": false, + "properties": { + "client": { + "type": "string", + "description": "The client's platform name.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `\"website\"` as the server no longer stores which\nclient submitted presence updates.\n" + }, + "status": { + "type": "string", + "enum": ["idle", "active"], + "description": "The status of the user on this client. Will be either `idle`\nor `active`.\n" + }, + "timestamp": { + "type": "integer", + "description": "The UNIX timestamp of when this client sent the user's presence\nto the server with the precision of a second.\n" + }, + "pushable": { + "type": "boolean", + "description": "Whether the client is capable of showing mobile/push notifications\nto the user.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `false` as the server no longer stores which\nclient submitted presence updates.\n" + } + } + } + } + }, + "additionalProperties": false, + "example": { + "type": "presence", + "user_id": 10, + "email": "user10@zulip.testserver", + "server_timestamp": 1594825445.3200784, + "presence": { + "website": { + "client": "website", + "status": "idle", + "timestamp": 1594825445, + "pushable": false + } + }, + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent when a new channel is created to users who can see\nthe new channel exists (for private channels, only subscribers and\norganization administrators will receive this event).\n\nThis event is also sent when a user gains access to a channel they\npreviously [could not access](/help/channel-permissions), such as\nwhen their [role](/help/user-roles) changes, a\nprivate channel is made public, or a guest user is subscribed\nto a public (or private) channel.\n\nThis event is also sent when a channel is unarchived but only\nto clients that did not declare the `archived_channels` [client\ncapability][client-capabilities].\n\nNote that organization administrators who are not subscribed will\nnot be able to see content on the channel; just that it exists.\n\n**Changes**: Prior to Zulip 11.0 (feature level 378), this\nevent was sent to all the users who could see the channel when it\nwas unarchived.\n\nPrior to Zulip 8.0 (feature level 220), this event was incorrectly\nnot sent to guest users a web-public channel was created.\n\nPrior to Zulip 8.0 (feature level 205), this event was not sent\nwhen a user gained access to a channel due to their role changing.\n\nPrior to Zulip 8.0 (feature level 192), this event was not sent\nwhen guest users gained access to a public channel by being\nsubscribed.\n\nPrior to Zulip 6.0 (feature level 134), this event was not sent\nwhen a private channel was made public.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["stream"] + } + ] + }, + "op": { + "type": "string", + "enum": ["create"] + }, + "streams": { + "type": "array", + "description": "Array of objects, each containing\ndetails about the newly added channel(s).\n", + "items": { + "$ref": "#/components/schemas/BasicChannel" + } + } + }, + "additionalProperties": false, + "example": { + "type": "stream", + "op": "create", + "streams": [ + { + "name": "private", + "stream_id": 12, + "is_archived": false, + "description": "", + "rendered_description": "", + "date_created": 1691057093, + "creator_id": 11, + "invite_only": true, + "is_web_public": false, + "stream_post_policy": 1, + "history_public_to_subscribers": false, + "first_message_id": null, + "folder_id": 1, + "is_recently_active": true, + "message_retention_days": null, + "is_announcement_only": false, + "can_add_subscribers_group": 2, + "can_remove_subscribers_group": 2, + "can_subscribe_group": 2, + "stream_weekly_traffic": null, + "subscriber_count": 0 + } + ], + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent when a user loses access to a channel they previously\n[could access](/help/channel-permissions) because they are\nunsubscribed from a private channel or their [role](/help/user-roles)\nhas changed.\n\nThis event is also sent when a channel is archived but only\nto clients that did not declare the `archived_channels` [client\ncapability][client-capabilities].\n\n**Changes**: Prior to Zulip 11.0 (feature level 378), this\nevent was sent to all the users who could see the channel when it\nwas archived.\n\nPrior to Zulip 8.0 (feature level 205), this event was not sent\nwhen a user lost access to a channel due to their role changing.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["stream"] + } + ] + }, + "op": { + "type": "string", + "enum": ["delete"] + }, + "streams": { + "type": "array", + "deprecated": true, + "description": "Array of objects, each containing ID of the channel that was deleted.\n\n**Changes**: **Deprecated** in Zulip 10.0 (feature level 343)\nand will be removed in a future release. Previously, these\nobjects additionally contained all the standard fields for a\nchannel object.\n", + "items": { + "type": "object", + "properties": { + "stream_id": { + "type": "integer", + "description": "ID of the deleted channel.\n" + } + }, + "additionalProperties": false + } + }, + "stream_ids": { + "type": "array", + "description": "Array containing the IDs of the channels that were deleted.\n\n**Changes**: New in Zulip 10.0 (feature level 343). Previously,\nthese IDs were available only via the legacy `streams` array.\n", + "items": { + "type": "integer" + } + } + }, + "additionalProperties": false, + "example": { + "type": "stream", + "op": "delete", + "streams": [ + { + "stream_id": 1 + }, + { + "stream_id": 2 + } + ], + "stream_ids": [1, 2], + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to all users who can see that a channel exists\nwhen a property of that channel changes. See\n[GET /streams](/api/get-streams#response) response\nfor details on the various properties of a channel.\n\nThis event is also sent when archiving or unarchiving a\nchannel to all the users who can see that channel exists\nbut only to the clients that declared the `archived_channels`\n[client capability][client-capabilities].\n\n**Changes**: Prior to Zulip 11.0 (feature level 378),\nthis event was never sent when archiving or unarchiving\na channel.\n\nBefore Zulip 9.0 (feature level 256), this event was never\nsent when the `first_message_id` property of a channel was\nupdated because the oldest message that had been sent to it\nchanged.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["stream"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "stream_id": { + "type": "integer", + "description": "The ID of the channel whose details have changed.\n" + }, + "name": { + "type": "string", + "description": "The name of the channel whose details have changed.\n" + }, + "property": { + "type": "string", + "description": "The property of the channel which has changed. See\n[GET /streams](/api/get-streams#response) response for details\non the various properties of a channel.\n\nClients should handle an \"unknown\" property received here without\ncrashing, since that can happen when connecting to a server running a\nnewer version of Zulip with new features.\n" + }, + "value": { + "description": "The new value of the changed property.\n\n**Changes**: Starting with Zulip 11.0 (feature level 389),\nthis value can be `null` when a channel is removed from the folder.\n\nStarting with Zulip 10.0 (feature level 320), this\nfield can be an object for `can_remove_subscribers_group` property,\nwhich is a [group-setting value][setting-values], when the setting\nis set to a combination of users and groups.\n\n[setting-values]: /api/group-setting-values\n", + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "direct_members": { + "description": "The list of IDs of individual users in the collection of users with this permission.\n", + "type": "array", + "items": { + "type": "integer" + } + }, + "direct_subgroups": { + "description": "The list of IDs of the groups in the collection of users with this permission.\n", + "type": "array", + "items": { + "type": "integer" + } + } + }, + "description": "If an object, it will be a [group-setting value][setting-values] with these fields:\n\n[setting-values]: /api/group-setting-values\n" + }, + { + "type": "integer" + }, + { + "type": "boolean" + }, + { + "type": "string", + "nullable": true + } + ] + }, + "rendered_description": { + "type": "string", + "description": "Note: Only present if the changed property was `description`.\n\nThe short description of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "history_public_to_subscribers": { + "type": "boolean", + "description": "Note: Only present if the changed property was `invite_only`.\n\nWhether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" + }, + "is_web_public": { + "type": "boolean", + "description": "Note: Only present if the changed property was `invite_only`.\n\nWhether the channel's history is now readable by web-public spectators.\n\n**Changes**: New in Zulip 5.0 (feature level 71).\n" + } + }, + "additionalProperties": false, + "example": { + "op": "update", + "type": "stream", + "property": "invite_only", + "value": true, + "history_public_to_subscribers": true, + "is_web_public": false, + "stream_id": 11, + "name": "test", + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent when a reaction is added to a message.\nSent to all users who were recipients of the message.\n", + "allOf": [ + { + "$ref": "#/components/schemas/EmojiReactionEvent" + }, + { + "additionalProperties": false, + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["reaction"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "message_id": { + "type": "integer", + "description": "The ID of the message to which a reaction was\nadded.\n" + }, + "emoji_code": {}, + "emoji_name": {}, + "reaction_type": {}, + "user_id": {}, + "user": {} + }, + "example": { + "type": "reaction", + "op": "add", + "user_id": 10, + "user": { + "user_id": 10, + "email": "user10@zulip.testserver", + "full_name": "King Hamlet" + }, + "message_id": 32, + "emoji_name": "tada", + "emoji_code": "1f389", + "reaction_type": "unicode_emoji", + "id": 0 + } + } + ] + }, + { + "type": "object", + "description": "Event sent when a reaction is removed from a message.\nSent to all users who were recipients of the message.\n", + "allOf": [ + { + "$ref": "#/components/schemas/EmojiReactionEvent" + }, + { + "additionalProperties": false, + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["reaction"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "message_id": { + "type": "integer", + "description": "The ID of the message from which the reaction was\nremoved.\n" + }, + "emoji_code": {}, + "emoji_name": {}, + "reaction_type": {}, + "user_id": {}, + "user": {} + }, + "example": { + "type": "reaction", + "op": "remove", + "user_id": 10, + "user": { + "user_id": 10, + "email": "user10@zulip.testserver", + "full_name": "King Hamlet" + }, + "message_id": 52, + "emoji_name": "tada", + "emoji_code": "1f389", + "reaction_type": "unicode_emoji", + "id": 0 + } + } + ] + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when the user uploads a new file\nin a Zulip message. Useful to implement live update in UI showing all files\nthe current user has uploaded.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["attachment"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "attachment": { + "$ref": "#/components/schemas/Attachment" + }, + "upload_space_used": { + "type": "integer", + "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" + } + }, + "example": { + "type": "attachment", + "op": "add", + "attachment": { + "id": 1, + "name": "zulip.txt", + "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", + "size": 6, + "create_time": 1594825414000, + "messages": [] + }, + "upload_space_used": 6, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when details of a file that user\nuploaded are changed. Most updates will be changes in the list of\nmessages that reference the uploaded file.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["attachment"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "attachment": { + "$ref": "#/components/schemas/Attachment" + }, + "upload_space_used": { + "type": "integer", + "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" + } + }, + "example": { + "type": "attachment", + "op": "update", + "attachment": { + "id": 1, + "name": "zulip.txt", + "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", + "size": 6, + "create_time": 1594825414000, + "messages": [] + }, + "upload_space_used": 6, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when the user deletes a file\nthey had uploaded. Useful primarily for UI showing all the files\nthe current user has uploaded.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["attachment"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "attachment": { + "type": "object", + "description": "Dictionary containing the ID of the deleted attachment.\n", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "The ID of the deleted attachment.\n" + } + } + }, + "upload_space_used": { + "type": "integer", + "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" + } + }, + "example": { + "type": "attachment", + "op": "remove", + "attachment": { + "id": 1 + }, + "upload_space_used": 0, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when the metadata in the\n`push_devices` dictionary for the user changes.\n\nHelps clients to live-update the `push_devices` dictionary\nreturned in [`POST /register`](/api/register-queue) response.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["push_device"] + } + ] + }, + "push_account_id": { + "type": "string", + "description": "The push account ID for this client registration.\n\nSee [`POST /mobile_push/register`](/api/register-push-device)\nfor details on push account IDs.\n" + }, + "status": { + "type": "string", + "enum": ["active", "failed", "pending"], + "description": "The updated registration status. Will be `\"active\"`, `\"failed\"`, or\n`\"pending\"`.\n" + }, + "error_code": { + "type": "string", + "nullable": true, + "description": "If the status is `\"failed\"`, a [Zulip API error\ncode](/api/rest-error-handling) indicating the type of failure that\noccurred.\n\nThe following error codes have recommended client behavior:\n\n- `\"INVALID_BOUNCER_PUBLIC_KEY\"` - Inform the user to update app.\n- `\"REQUEST_EXPIRED` - Retry with a fresh payload.\n If the status is \"failed\", an error code explaining the failure.\n" + } + }, + "example": { + "id": 1, + "type": "push_device", + "push_account_id": "1234", + "status": "active" + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a submessage is added to a message.\n\nSubmessages are an **experimental** API used for widgets such as the\n`/poll` widget in Zulip.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["submessage"] + } + ] + }, + "msg_type": { + "type": "string", + "description": "The type of the message.\n" + }, + "content": { + "type": "string", + "description": "The new content of the submessage.\n" + }, + "message_id": { + "type": "integer", + "description": "The ID of the message to which the submessage has been added.\n" + }, + "sender_id": { + "type": "integer", + "description": "The ID of the user who sent the message.\n" + }, + "submessage_id": { + "type": "integer", + "description": "The ID of the submessage.\n" + } + }, + "example": { + "type": "submessage", + "msg_type": "widget", + "message_id": 970461, + "submessage_id": 4737, + "sender_id": 58, + "content": "{\"type\":\"vote\",\"key\":\"58,1\",\"vote\":1}", + "id": 28 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users who can access the modified\nuser when the status of a user changes.\n\n**Changes**: Prior to Zulip 8.0 (feature level 228),\nthis event was sent to all users in the organization.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_status"] + } + ] + }, + "away": { + "type": "boolean", + "deprecated": true, + "description": "Whether the user has marked themself \"away\" with this status.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n" + }, + "status_text": { + "type": "string", + "description": "The text content of the status message.\n\nThis will be `\"\"` for users who set a status without selecting\nor writing a message.\n" + }, + "emoji_name": { + "type": "string", + "description": "The [emoji name](/api/update-status#parameter-emoji_name) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + }, + "emoji_code": { + "type": "string", + "description": "The [emoji code](/api/update-status#parameter-emoji_code) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + }, + "reaction_type": { + "type": "string", + "enum": [ + "unicode_emoji", + "realm_emoji", + "zulip_extra_emoji" + ], + "description": "The [emoji type](/api/update-status#parameter-reaction_type) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + }, + "user_id": { + "type": "integer", + "description": "The ID of the user whose status changed.\n" + } + }, + "example": { + "type": "user_status", + "user_id": 10, + "away": true, + "status_text": "out to lunch", + "emoji_name": "car", + "emoji_code": "1f697", + "reaction_type": "unicode_emoji", + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when new custom\nprofile field types are configured for that Zulip organization.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["custom_profile_fields"] + } + ] + }, + "fields": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains\ndetails of a single new custom profile field for the Zulip\norganization.\n", + "items": { + "$ref": "#/components/schemas/CustomProfileField" + } + } + }, + "example": { + "type": "custom_profile_fields", + "fields": [ + { + "id": 1, + "name": "Phone number", + "type": 1, + "hint": "", + "field_data": "", + "order": 1, + "required": true, + "editable_by_user": true + }, + { + "id": 2, + "name": "Biography", + "type": 2, + "hint": "What are you known for?", + "field_data": "", + "order": 2, + "required": true, + "editable_by_user": true + }, + { + "id": 3, + "name": "Favorite food", + "type": 1, + "hint": "Or drink, if you'd prefer", + "field_data": "", + "order": 3, + "required": false, + "editable_by_user": true + }, + { + "id": 4, + "name": "Favorite editor", + "type": 3, + "hint": "", + "field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}", + "order": 4, + "display_in_profile_summary": true, + "required": true, + "editable_by_user": true + }, + { + "id": 5, + "name": "Birthday", + "type": 4, + "hint": "", + "field_data": "", + "order": 5, + "required": false, + "editable_by_user": false + }, + { + "id": 6, + "name": "Favorite website", + "type": 5, + "hint": "Or your personal blog's URL", + "field_data": "", + "order": 6, + "display_in_profile_summary": true, + "required": false, + "editable_by_user": true + }, + { + "id": 7, + "name": "Mentor", + "type": 6, + "hint": "", + "field_data": "", + "order": 7, + "required": true, + "editable_by_user": false + }, + { + "id": 8, + "name": "GitHub", + "type": 7, + "hint": "Enter your GitHub username", + "field_data": "{\"subtype\":\"github\"}", + "order": 8, + "required": true, + "editable_by_user": true + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when an organization\nadministrator changes the organization's configured default channel groups.\n\nDefault channel groups are an **experimental** feature that is not yet\nstabilized.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["default_stream_groups"] + } + ] + }, + "default_stream_groups": { + "type": "array", + "description": "An array of dictionaries where each dictionary\ncontains details about a single default channel group.\n", + "items": { + "$ref": "#/components/schemas/DefaultChannelGroup" + } + } + }, + "example": { + "type": "default_stream_groups", + "default_stream_groups": [ + { + "name": "group1", + "id": 2, + "description": "New description", + "streams": [3, 1, 5] + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the\ndefault channels in the organization are changed by an\norganization administrator.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["default_streams"] + } + ] + }, + "default_streams": { + "type": "array", + "description": "An array of IDs of all the [default channels](/help/set-default-streams-for-new-users)\nin the organization.\n\n**Changes**: Before Zulip 10.0 (feature level 330),\nwe sent array of dictionaries where each dictionary\ncontained details about a single default stream for\nthe Zulip organization.\n", + "items": { + "type": "integer" + } + } + }, + "example": { + "type": "default_streams", + "default_streams": [2, 3], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a message has been deleted.\n\nSent to all users who currently are subscribed to the\nmessages' recipient. May also be sent to additional users\nwho had access to it, including, in particular, an\nadministrator user deleting messages in a stream that they\nare not subscribed to.\n\nThis means that clients can assume that they will always\nreceive an event of this type for deletions that the\nclient itself initiated.\n\nThis event is also sent when the user loses access to a message,\nsuch as when it is [moved to a channel][message-move-channel] that\nthe user does not [have permission to access][channel-access].\n\n**Changes**: Before Zulip 9.0 (feature level 274), this\nevent was only sent to subscribers of the message's recipient.\n\nBefore Zulip 5.0 (feature level 77), events\nfor direct messages contained additional `sender_id` and\n`recipient_id` fields.\n\n[message-move-channel]: /help/move-content-to-another-channel\n[channel-access]: /help/channel-permissions\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["delete_message"] + } + ] + }, + "message_ids": { + "type": "array", + "description": "Only present for clients that support the `bulk_message_deletion`\n[client capability][client-capabilities].\n\nA sorted list containing the IDs of the newly deleted messages.\n\n**Changes**: Before Zulip 11.0 (feature level 393), this list was\nnot guaranteed to be sorted.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", + "items": { + "type": "integer" + } + }, + "message_id": { + "type": "integer", + "description": "Only present for clients that do not support the `bulk_message_deletion`\n[client capability][client-capabilities].\n\nThe ID of the newly deleted message.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "message_type": { + "type": "string", + "description": "The type of message. Either `\"stream\"` or `\"private\"`.\n", + "enum": ["private", "stream"] + }, + "stream_id": { + "type": "integer", + "description": "Only present if `message_type` is `\"stream\"`.\n\nThe ID of the channel to which the message was sent.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `message_type` is `\"stream\"`.\n\nThe topic to which the message was sent.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name was empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + } + }, + "example": { + "type": "delete_message", + "message_type": "private", + "message_id": 37, + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to a user's clients when that user's set of\nconfigured muted topics have changed.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["muted_topics"] + } + ] + }, + "muted_topics": { + "type": "array", + "deprecated": true, + "description": "Array of tuples, where each tuple describes a muted topic.\nThe first element of the tuple is the channel name in which the topic\nhas to be muted, the second element is the topic name to be muted\nand the third element is an integer UNIX timestamp representing\nwhen the topic was muted.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level\n134). Starting with this version, clients that explicitly\nrequested the replacement `user_topic` event type when\nregistering their event queue will not receive this legacy\nevent type.\n\nBefore Zulip 3.0 (feature level 1), the `muted_topics`\narray objects were 2-item tuples and did not include the timestamp\ninformation for when the topic was muted.\n", + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + } + ] + } + } + } + }, + "additionalProperties": false, + "example": { + "type": "muted_topics", + "muted_topics": [ + ["Denmark", "topic", 1594825442] + ], + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to a user's clients when the user mutes/unmutes\na topic, or otherwise modifies their personal per-topic\nconfiguration.\n\n**Changes**: New in Zulip 6.0 (feature level 134). Previously,\nclients were notified about changes in muted topic\nconfiguration via the `muted_topics` event type.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_topic"] + } + ] + }, + "stream_id": { + "type": "integer", + "description": "The ID of the channel to which the topic belongs.\n" + }, + "topic_name": { + "type": "string", + "description": "The name of the topic.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "last_updated": { + "type": "integer", + "description": "An integer UNIX timestamp representing when the user-topic\nrelationship was last changed.\n" + }, + "visibility_policy": { + "type": "integer", + "description": "An integer indicating the user's visibility\npreferences for the topic, such as whether the topic\nis muted.\n\n- 0 = None. Used to indicate that the user no\n longer has a special visibility policy for this topic.\n- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).\n- 2 = Unmuted. Used to record unmuted topics.\n- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n\nIn Zulip 7.0 (feature level 170), added unmuted as a visibility\npolicy option.\n" + } + }, + "additionalProperties": false, + "example": { + "id": 1, + "type": "user_topic", + "stream_id": 1, + "topic_name": "topic", + "last_updated": 1594825442, + "visibility_policy": 1 + } + }, + { + "type": "object", + "description": "Event sent to a user's clients when that user's set of\nconfigured [muted users](/api/mute-user) have changed.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["muted_users"] + } + ] + }, + "muted_users": { + "type": "array", + "description": "A list of dictionaries where each dictionary describes\na muted user.\n", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the user ID and timestamp of a muted user.\n", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the muted user.\n" + }, + "timestamp": { + "type": "integer", + "description": "An integer UNIX timestamp representing when the user was muted.\n" + } + } + } + } + }, + "additionalProperties": false, + "example": { + "type": "muted_users", + "muted_users": [ + { + "id": 1, + "timestamp": 1594825442 + }, + { + "id": 22, + "timestamp": 1654865392 + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Heartbeat events are sent by the server to avoid\nlongpolling connections being affected by networks that\nkill idle HTTP connections.\n\nClients do not need to do anything to process these\nevents, beyond the common `last_event_id` accounting.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["heartbeat"] + } + ] + } + }, + "example": { + "type": "heartbeat", + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when the set of onboarding steps to show for the current user\nhas changed (e.g. because the user dismissed one).\n\nClients that feature a similar tutorial experience to the Zulip web app\nmay want to handle these events.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this event was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["onboarding_steps"] + } + ] + }, + "onboarding_steps": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains details about a\nsingle onboarding step.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this array was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported, and the `type` field in these objects did not\nexist as all onboarding steps were implicitly hotspots.\n", + "items": { + "$ref": "#/components/schemas/OnboardingStep" + } + } + }, + "example": { + "type": "onboarding_steps", + "onboarding_steps": [ + { + "type": "one_time_notice", + "name": "visibility_policy_banner" + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a message's content, topic and/or\nchannel has been edited or when a message's content\nhas a rendering update, such as for an\n[inline URL preview][inline-url-previews].\nSent to all users who had received the original\nmessage.\n\n[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews\n\n**Changes**: In Zulip 10.0 (feature level 284), removed the\n`prev_rendered_content_version` field as it is an internal\nserver implementation detail not used by any client.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["update_message"] + } + ] + }, + "user_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who sent the message.\n\nWill be `null` when event is for a rendering update of the original\nmessage, such as for an [inline URL preview][inline-url-previews].\n\n**Changes**: Prior to Zulip 5.0 (feature level 114), this field was\nomitted for [inline URL preview][inline-url-previews] updates.\n" + }, + "rendering_only": { + "type": "boolean", + "description": "Whether the event only updates the rendered content of the message.\n\nThis field should be used by clients to determine if the event\nonly provides a rendering update to the message content,\nsuch as for an [inline URL preview][inline-url-previews].\nWhen `true`, the event does not reflect a user-generated edit\nand does not modify the message history.\n\n**Changes**: New in Zulip 5.0 (feature level 114). Clients can\ncorrectly identify these rendering update events prior to this\nfeature level by checking whether the `user_id` field was omitted.\n" + }, + "message_id": { + "type": "integer", + "description": "The ID of the message which was edited or updated.\n\nThis field should be used to apply content edits to the client's\ncached message history, or to apply rendered content updates.\n\nIf the channel or topic was changed, the set of moved messages is\nencoded in the separate `message_ids` field, which is guaranteed\nto include `message_id`.\n" + }, + "message_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A sorted list of IDs of messages to which any channel or topic\nchanges encoded in this event should be applied.\n\nThis list always includes `message_id`, even when there are no\nchannel or topic changes to apply.\n\nThese messages are guaranteed to have all been previously sent\nto channel `stream_id` with topic `orig_subject`, and have been\nmoved to `new_stream_id` with topic `subject` (if those fields\nare present in the event).\n\nClients processing these events should update all cached message\nhistory associated with the moved messages (including adjusting\n`unread_msgs` data structures, where the client may not have the\nmessage itself in its history) to reflect the new channel and\ntopic.\n\nContent changes should be applied only to the single message\nindicated by `message_id`.\n\n**Changes**: Before Zulip 11.0 (feature level 393), this list\nwas not guaranteed to be sorted.\n" + }, + "flags": { + "type": "array", + "description": "The user's personal [message flags][message-flags] for the\nmessage with ID `message_id` following the edit.\n\nA client application should compare these to the original flags\nto identify cases where a mention or alert word was added by the\nedit.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", + "items": { + "type": "string" + } + }, + "edit_timestamp": { + "type": "integer", + "description": "The UNIX timestamp when this message edit operation was processed by\nthe server, in UTC seconds.\n\n**Changes**: Prior to Zulip 5.0 (feature level 114), this field\nwas omitted for [inline URL preview][inline-url-previews] updates.\n" + }, + "stream_name": { + "type": "string", + "description": "Only present if the message was edited and originally sent to a channel.\n\nThe name of the channel that the message was sent to. Clients\nare recommended to use the `stream_id` field instead.\n" + }, + "stream_id": { + "type": "integer", + "description": "Only present if the message was edited and originally sent to a channel.\n\nThe pre-edit channel for all of the messages with IDs in\n`message_ids`.\n\n**Changes**: As of Zulip 5.0 (feature level 112), this field\nis present for all edits to a channel message. Previously, it\nwas not present when only the content of the channel message was\nedited.\n" + }, + "new_stream_id": { + "type": "integer", + "description": "Only present if message(s) were moved to a different channel.\n\nThe post-edit channel for all of the messages with IDs in\n`message_ids`.\n" + }, + "propagate_mode": { + "type": "string", + "description": "Only present if this event moved messages to a different\ntopic and/or channel.\n\nThe choice the editing user made about which messages should be\naffected by a channel/topic edit:\n\n- `\"change_one\"`: Just change the one indicated in `message_id`.\n- `\"change_later\"`: Change messages in the same topic that had\n been sent after this one.\n- `\"change_all\"`: Change all messages in that topic.\n\nThis parameter should be used to decide whether to change\nnavigation and compose box state in response to the edit. For\nexample, if the user was previously in topic narrow, and the\ntopic was edited with `\"change_later\"` or `\"change_all\"`, the Zulip\nweb app will automatically navigate to the new topic narrow.\nSimilarly, a message being composed to the old topic should\nhave its recipient changed to the new topic.\n\nThis navigation makes it much more convenient to move content\nbetween topics without disruption or messages continuing\nto be sent to the pre-edit topic by accident.\n", + "enum": [ + "change_one", + "change_later", + "change_all" + ] + }, + "orig_subject": { + "type": "string", + "description": "Only present if this event moved messages to a different\ntopic and/or channel.\n\nThe pre-edit topic for all of the messages with IDs in\n`message_ids`.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual pre-edit topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "subject": { + "type": "string", + "description": "Only present if this event moved messages to a different topic;\nthis field will not be present when moving messages to the same\ntopic name in a different channel.\n\nThe post-edit topic for all of the messages with IDs in\n`message_ids`.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual post-edit topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "topic_links": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "text": { + "type": "string", + "description": "The original link text present in the topic.\n" + }, + "url": { + "type": "string", + "description": "The expanded target url which the link points to.\n" + } + } + }, + "description": "Only present if this event moved messages to a different topic;\nthis field will not be present when moving messages to the same\ntopic name in a different channel.\n\nData on any links to be included in the `topic`\nline (these are generated by\n[custom linkification filter](/help/add-a-custom-linkifier)\nthat match content in the message's topic.), corresponding\nto the post-edit topic.\n\n**Changes**: This field contained a list of urls before\nZulip 4.0 (feature level 46).\n\nNew in Zulip 3.0 (feature level 1). Previously, this field\nwas called `subject_links`; clients are recommended to\nrename `subject_links` to `topic_links` if present for\ncompatibility with older Zulip servers.\n" + }, + "orig_content": { + "type": "string", + "description": "Only present if this event changed the message content.\n\nThe original content of the message with ID `message_id`\nimmediately prior to this edit, in the original [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n" + }, + "orig_rendered_content": { + "type": "string", + "description": "Only present if this event changed the message content.\n\nThe original content of the message with ID `message_id`\nimmediately prior to this edit, rendered as HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "content": { + "type": "string", + "description": "Only present if this event changed the message content or\nupdated the message content for an\n[inline URL preview][inline-url-previews].\n\nThe new content of the message with ID `message_id`, in the\noriginal [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n" + }, + "rendered_content": { + "type": "string", + "description": "Only present if this event changed the message content or\nupdated the message content for an\n[inline URL preview][inline-url-previews].\n\nThe new content of the message with ID `message_id`,\nrendered in HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "is_me_message": { + "type": "boolean", + "description": "Only present if this event changed the message content.\n\nWhether the message with ID `message_id` is now a\n[/me status message][status-messages].\n\n[status-messages]: /help/format-your-message-using-markdown#status-messages\n" + } + }, + "required": [ + "type", + "id", + "user_id", + "message_id", + "message_ids", + "flags", + "edit_timestamp", + "rendering_only" + ], + "example": { + "type": "update_message", + "user_id": 10, + "edit_timestamp": 1594825451, + "message_id": 58, + "stream_name": "Verona", + "orig_content": "hello", + "orig_rendered_content": "

hello

", + "content": "new content", + "rendered_content": "

new content

", + "is_me_message": false, + "propagate_mode": "change_all", + "stream_id": 5, + "orig_subject": "test", + "subject": "new_topic", + "topic_links": [], + "message_ids": [57, 58], + "flags": [], + "rendering_only": false, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a user starts typing a message.\n\nSent to all clients for users who would receive the\nmessage being typed, with the additional rule that typing\nnotifications for channel messages are only sent to clients\nthat included `stream_typing_notifications` in their\n[client capabilities][client-capabilities] when registering\nthe event queue.\n\nSee [POST /typing](/api/set-typing-status) endpoint for more details.\n\n**Changes**: Typing notifications for channel messages are new in\nZulip 4.0 (feature level 58).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["typing"] + } + ] + }, + "op": { + "type": "string", + "enum": ["start"] + }, + "message_type": { + "type": "string", + "description": "Type of message being composed. Must be `\"stream\"` or `\"direct\"`.\n\n**Changes**: In Zulip 8.0 (feature level 215), replaced the\nvalue `\"private\"` with `\"direct\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously, all typing\nnotifications were implicitly direct messages.\n", + "enum": ["direct", "stream"] + }, + "sender": { + "additionalProperties": false, + "type": "object", + "description": "Object describing the user who is typing the message.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The user's ID.\n" + }, + "email": { + "type": "string", + "description": "The Zulip API email address for the user.\n" + } + } + }, + "recipients": { + "type": "array", + "description": "Only present if `message_type` is `\"direct\"`.\n\nArray of dictionaries describing the set of users who would be\nrecipients of the message being typed. Each dictionary contains\ndetails about one of the recipients. The sending user is guaranteed\nto appear among the recipients.\n", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the user ID and Zulip API email of a recipient.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The ID of the user.\n" + }, + "email": { + "type": "string", + "description": "The Zulip API email address for the user.\n" + } + } + } + }, + "stream_id": { + "type": "integer", + "description": "Only present if `message_type` is `\"stream\"`.\n\nThe unique ID of the channel to which message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `message_type` is `\"stream\"`.\n\nTopic within the channel where the message is being typed.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + } + }, + "example": { + "type": "typing", + "op": "start", + "message_type": "direct", + "sender": { + "user_id": 10, + "email": "user10@zulip.testserver" + }, + "recipients": [ + { + "user_id": 8, + "email": "user8@zulip.testserver" + }, + { + "user_id": 10, + "email": "user10@zulip.testserver" + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a user stops typing a message.\n\nSent to all clients for users who would receive the message\nthat was previously being typed, with the additional rule\nthat typing notifications for channel messages are only sent to\nclients that included `stream_typing_notifications` in their\n[client capabilities][client-capabilities] when registering\nthe event queue.\n\nSee [POST /typing](/api/set-typing-status) endpoint for more details.\n\n**Changes**: Typing notifications for channel messages are new in\nZulip 4.0 (feature level 58).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["typing"] + } + ] + }, + "op": { + "type": "string", + "enum": ["stop"] + }, + "message_type": { + "type": "string", + "description": "Type of message being composed. Must be `\"stream\"` or `\"direct\"`.\n\n**Changes**: In Zulip 8.0 (feature level 215), replaced the\nvalue `\"private\"` with `\"direct\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously all typing\nnotifications were implicitly direct messages.\n", + "enum": ["direct", "stream"] + }, + "sender": { + "additionalProperties": false, + "type": "object", + "description": "Object describing the user who was previously typing the message.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The user's ID.\n" + }, + "email": { + "type": "string", + "description": "The Zulip API email address for the user.\n" + } + } + }, + "recipients": { + "type": "array", + "description": "Only present if `message_type` is `\"direct\"`.\n\nArray of dictionaries describing the set of users who would be\nrecipients of the message that was previously being typed. Each\ndictionary contains details about one of the recipients. The\nsending user is guaranteed to appear among the recipients.\n", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the user ID and email of a recipient.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The ID of the user.\n" + }, + "email": { + "type": "string", + "description": "The Zulip API email address for the user.\n" + } + } + } + }, + "stream_id": { + "type": "integer", + "description": "Only present if `message_type` is `\"stream\"`.\n\nThe unique ID of the channel to which message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `message_type` is `\"stream\"`.\n\nTopic within the channel where the message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" + } + }, + "example": { + "type": "typing", + "op": "stop", + "message_type": "direct", + "sender": { + "user_id": 10, + "email": "user10@zulip.testserver" + }, + "recipients": [ + { + "user_id": 8, + "email": "user8@zulip.testserver" + }, + { + "user_id": 10, + "email": "user10@zulip.testserver" + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a user starts editing a message.\nEvent sent when a user starts typing in a textarea to edit the\ncontent of a message. See the [edit message typing notifications\nendpoint](/api/set-typing-status-for-message-edit).\n\nClients requesting `typing_edit_message` event type that have\n`receives_typing_notifications` enabled will receive this event if\nthey would have been notified if the message's content edit were to\nbe saved (E.g., because they were a direct message recipient or\nare a subscribe to the channel).\n\n**Changes**: New in Zulip 10.0 (feature level 351). Previously,\ntyping notifications were not available when editing messages.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["typing_edit_message"] + } + ] + }, + "op": { + "type": "string", + "enum": ["start"] + }, + "sender_id": { + "type": "integer", + "description": "The ID of the user who is typing the edit of the\nmessage.\n\nClients should be careful to display this user as the person who\nis typing, not that of the sender of the message, in case a\ncollaborative editing feature be might be added in the future.\n" + }, + "message_id": { + "type": "integer", + "description": "Indicates the message id of the message that is being edited.\n" + }, + "recipient": { + "type": "object", + "description": "Object containing details about recipients of message edit typing notification.\n", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "description": "Type of message being composed. Must be `\"channel\"` or `\"direct\"`.\n", + "enum": ["direct", "channel"] + }, + "channel_id": { + "type": "integer", + "description": "Only present if `type` is `\"channel\"`.\n\nThe unique ID of the channel to which message is being edited.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `type` is `\"channel\"`.\n\nTopic within the channel where the message is being edited.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Present only if `type` is `direct`.\n\nThe user IDs of every recipient of this direct message.\n" + } + } + } + }, + "example": { + "type": "typing_edit_message", + "op": "start", + "sender_id": 10, + "recipient": { + "type": "direct", + "user_ids": [8, 10] + }, + "message_id": 7, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a user stops typing in a textarea to edit the\ncontent of a message. See the [edit message typing notifications\nendpoint](/api/set-typing-status-for-message-edit).\n\nClients requesting `typing_edit_message` event type that have\n`receives_typing_notifications` enabled will receive this event if\nthey would have been notified if the message's content edit were to\nbe saved (E.g., because they were a direct message recipient or\nare a subscribe to the channel).\n\n**Changes**: New in Zulip 10.0 (feature level 351). Previously,\ntyping notifications were not available when editing messages.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["typing_edit_message"] + } + ] + }, + "op": { + "type": "string", + "enum": ["stop"] + }, + "sender_id": { + "type": "integer", + "description": "The ID of the user who sent the message.\n" + }, + "message_id": { + "type": "integer", + "description": "Indicates the message id of the message that is being edited.\n" + }, + "recipient": { + "type": "object", + "description": "Object containing details about recipients of message edit typing notification.\n", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "description": "Type of message being composed. Must be `\"channel\"` or `\"direct\"`.\n", + "enum": ["direct", "channel"] + }, + "channel_id": { + "type": "integer", + "description": "Only present if `type` is `\"channel\"`.\n\nThe unique ID of the channel to which message is being edited.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `type` is `\"channel\"`.\n\nTopic within the channel where the message is being edited.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Present only if `type` is `direct`.\n\nThe user IDs of every recipient of this direct message.\n" + } + } + } + }, + "example": { + "type": "typing_edit_message", + "op": "stop", + "sender_id": 10, + "message_id": 31, + "recipient": { + "type": "direct", + "user_ids": [8, 10] + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user when [message flags][message-flags] are added\nto messages.\n\nThis can reflect a direct user action, or can be the indirect\nconsequence of another action. Whatever the cause, if there's a change\nin the set of message flags that the user has for a message, then an\n`update_message_flags` event will be sent with the change. Note\nthat this applies when the user already had access to the message, and\ncontinues to have access to it. When a message newly appears or\ndisappears, a [`message`][message-event] or\n[`delete_message`][message-delete] event is sent instead.\n\nSome examples of actions that trigger an `update_message_flags`\nevent:\n\n- The `\"starred\"` flag is added when the user chooses to [star a\n message](/help/star-a-message).\n- The `\"read\"` flag is added when the user marks messages as read by\n scrolling through them, or uses [Mark all messages as read][all-read]\n on a conversation.\n- The `\"read\"` flag is added when the user [mutes](/help/mute-a-user) a\n message's sender.\n- The `\"read\"` flag is added after the user unsubscribes from a channel,\n or messages are moved to a not-subscribed channel, provided the user\n can still access the messages at all. Note a\n [`delete_message`][message-delete] event is sent in the case where the\n user can no longer access the messages.\n\nIn some cases, a change in message flags that's caused by another change\nmay happen a short while after the original change, rather than\nsimultaneously. For example, when messages that were unread are moved to\na channel where the user is not subscribed, the resulting change in\nmessage flags (and the corresponding `update_message_flags` event with\nflag `\"read\"`) may happen later than the message move itself. The delay\nin that example is typically at most a few hundred milliseconds and can\nin rare cases be minutes or longer.\n\n[message-flags]: /api/update-message-flags#available-flags\n[message-event]: /api/get-events#message\n[message-delete]: /api/get-events#delete_message\n[all-read]: /help/marking-messages-as-read#mark-messages-in-multiple-topics-and-channels-as-read\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["update_message_flags"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "operation": { + "deprecated": true, + "description": "Old name for the `op` field in this event type.\n\n**Deprecated** in Zulip 4.0 (feature level 32), and\nreplaced by the `op` field.\n", + "type": "string", + "enum": ["add"] + }, + "flag": { + "type": "string", + "description": "The [flag][message-flags] that was added.\n" + }, + "messages": { + "type": "array", + "description": "Array containing the IDs of all messages to which\nthe flag was added.\n", + "items": { + "type": "integer" + } + }, + "all": { + "type": "boolean", + "description": "Whether the specified flag was added to all messages.\nThis field is only relevant for the `\"read\"` flag, and\nwill be `false` for all other flags.\n\nWhen `true` for the `\"read\"` flag, then the `messages`\narray will be empty.\n" + } + }, + "example": { + "type": "update_message_flags", + "op": "add", + "operation": "add", + "flag": "starred", + "messages": [63], + "all": false, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user when [message flags][message-flags] are\nremoved from messages.\n\nSee the description for the [`update_message_flags` op:\n`add`](/api/get-events#update_message_flags-add) event for\nmore details about these events.\n\n[message-flags]: /api/update-message-flags#available-flags\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["update_message_flags"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "operation": { + "deprecated": true, + "type": "string", + "description": "Old name for the `op` field in this event type.\n\n**Deprecated** in Zulip 4.0 (feature level 32), and\nreplaced by the `op` field.\n", + "enum": ["remove"] + }, + "flag": { + "type": "string", + "description": "The [flag][message-flags] to be removed.\n" + }, + "messages": { + "type": "array", + "description": "Array containing the IDs of the messages from which the flag\nwas removed.\n", + "items": { + "type": "integer" + } + }, + "all": { + "deprecated": true, + "type": "boolean", + "description": "Will be `false` for all specified flags.\n\n**Deprecated** and will be removed in a future release.\n" + }, + "message_details": { + "description": "Only present if the specified `flag` is `\"read\"`.\n\nA set of data structures describing the messages that\nare being marked as unread with additional details to\nallow clients to update the `unread_msgs` data\nstructure for these messages (which may not be\notherwise known to the client).\n\n**Changes**: New in Zulip 5.0 (feature level 121). Previously,\nmarking already read messages as unread was not\nsupported by the Zulip API.\n", + "type": "object", + "additionalProperties": { + "type": "object", + "description": "`{message_id}`: Object containing details about the\nmessage with the specified ID.\n", + "additionalProperties": false, + "required": ["type"], + "properties": { + "type": { + "type": "string", + "description": "The type of this message. Either `\"stream\"` or `\"private\"`.\n", + "enum": ["private", "stream"] + }, + "mentioned": { + "type": "boolean", + "description": "A flag which indicates whether the message contains a mention\nof the user.\n\nPresent only if the message mentions the current user.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Present only if `type` is `private`.\n\nThe user IDs of every recipient of this direct message, excluding yourself.\nWill be the empty list for a message you had sent to only yourself.\n" + }, + "stream_id": { + "type": "integer", + "description": "Present only if `type` is `\"stream\"`.\n\nThe ID of the channel where the message was sent.\n" + }, + "topic": { + "type": "string", + "description": "Present only if `type` is `\"stream\"`.\n\nName of the topic where the message was sent.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "unmuted_stream_msg": { + "type": "boolean", + "deprecated": true, + "description": "**Deprecated** internal implementation detail. Clients should\nignore this field as it will be removed in the future.\n" + } + } + } + } + }, + "example": { + "type": "update_message_flags", + "op": "remove", + "operation": "remove", + "flag": "starred", + "messages": [63], + "message_details": { + "63": { + "type": "stream", + "stream_id": 22, + "topic": "lunch" + } + }, + "all": false, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to users in an organization when a [user group](/help/user-groups) is created.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "group": { + "$ref": "#/components/schemas/UserGroup" + } + }, + "example": { + "type": "user_group", + "op": "add", + "group": { + "name": "backend", + "members": [12], + "creator_id": 9, + "date_created": 1717484476, + "description": "Backend team", + "id": 2, + "is_system_group": false, + "can_add_members_group": 16, + "can_join_group": 16, + "can_leave_group": 15, + "can_manage_group": 16, + "can_mention_group": 11, + "can_remove_members_group": 16 + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization\nwhen a property of a user group is changed.\n\nFor group deactivation, this event is only sent\nif `include_deactivated_groups` client capability\nis set to `true`.\n\nThis event is also sent when deactivating or reactivating\na user for settings set to anonymous user groups which the\nuser is direct member of. When deactivating the user, event\nis only sent to users who cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when deactivating or reactivating a user.\n\nPrior to Zulip 10.0 (feature level 294), this event was sent to\nall clients when a user group was deactivated.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the user group whose details have changed.\n" + }, + "data": { + "type": "object", + "additionalProperties": false, + "description": "Dictionary containing the changed details of the user group.\n", + "properties": { + "name": { + "type": "string", + "description": "The new name of the user group. Only present if the group's name changed.\n" + }, + "description": { + "type": "string", + "description": "The new description of the group. Only present if the description\nchanged.\n" + }, + "can_add_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this group. Only present if this user\ngroup permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_join_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this group. Only present if this user group\npermission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_leave_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this group. Only present if this user group\npermission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_manage_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this group][manage-user-groups]. Only present\nif this user group permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" + } + ] + }, + "can_mention_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions]. Only present\nif this user group permission setting changed.\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" + } + ] + }, + "can_remove_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this group. Only present if this\nuser group permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "deactivated": { + "type": "boolean", + "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" + } + } + } + }, + "example": { + "type": "user_group", + "op": "update", + "group_id": 2, + "data": { + "description": "Mention this group to get the security team's attention." + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when users have been added to a user group.\n\nThis event is also sent when reactivating a user for all the user\ngroups the reactivated user was a member of before being deactivated.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when reactivating a user.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add_members"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the user group with new members.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the IDs of the users who have been added\nto the user group.\n" + } + }, + "example": { + "type": "user_group", + "op": "add_members", + "group_id": 2, + "user_ids": [10], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when users have been removed from\na user group.\n\nThis event is also sent when deactivating a user, for all\nthe user groups the deactivated user is a member of, but only\nto the users who cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303),\nthis event can also be sent when deactivating a user.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove_members"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the user group whose details have changed.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the IDs of the users who have been removed\nfrom the user group.\n" + } + }, + "example": { + "type": "user_group", + "op": "remove_members", + "group_id": 2, + "user_ids": [10], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when subgroups have been added to\na user group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add_subgroups"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the user group whose details have changed.\n" + }, + "direct_subgroup_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the IDs of the subgroups that have been added\nto the user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nPreviously, this was called `subgroup_ids`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" + } + }, + "example": { + "type": "user_group", + "op": "add_subgroups", + "group_id": 2, + "direct_subgroup_ids": [10], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when subgroups have been removed from\na user group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove_subgroups"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the user group whose details have changed.\n" + }, + "direct_subgroup_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the IDs of the subgroups that have been\nremoved from the user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nPreviously, this was called `subgroup_ids`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" + } + }, + "example": { + "type": "user_group", + "op": "remove_subgroups", + "group_id": 2, + "direct_subgroup_ids": [10], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent when a user group is deactivated but only to clients\nwith `include_deactivated_groups` client capability set to `false`.\n\n**Changes**: Prior to Zulip 10.0 (feature level 294), this\nevent was sent when a user group was deleted.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["user_group"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "group_id": { + "type": "integer", + "description": "The ID of the group which has been deleted.\n" + } + }, + "example": { + "type": "user_group", + "op": "remove", + "group_id": 2, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the\nset of configured [linkifiers](/help/add-a-custom-linkifier)\nfor the organization has changed.\n\nProcessing this event is important for doing Markdown local echo\ncorrectly.\n\nClients will not receive this event unless the event queue is\nregistered with the client capability\n`{\"linkifier_url_template\": true}`.\nSee [`POST /register`](/api/register-queue#parameter-client_capabilities)\nfor how client capabilities can be specified.\n\n**Changes**: Before Zulip 7.0 (feature level 176), the\n`linkifier_url_template` client capability was not required. The\nrequirement was added because linkifiers were updated to contain\na URL template instead of a URL format string, which was not a\nbackwards-compatible change.\n\nNew in Zulip 4.0 (feature level 54), replacing the deprecated\n`realm_filters` event type.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_linkifiers"] + } + ] + }, + "realm_linkifiers": { + "type": "array", + "description": "An ordered array of dictionaries where each dictionary contains\ndetails about a single linkifier.\n\nClients should always process linkifiers in the order given;\nthis is important if the realm has linkifiers with overlapping\npatterns. The order can be modified using [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "pattern": { + "type": "string", + "description": "The [Python regular expression](https://docs.python.org/3/howto/regex.html)\nthat represents the pattern that should be linkified by this linkifier.\n" + }, + "url_template": { + "type": "string", + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant\nURL template to be used for linkifying matches.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the linkifier.\n" + } + } + } + } + }, + "example": { + "type": "realm_linkifiers", + "realm_linkifiers": [ + { + "pattern": "#(?P[123])", + "url_template": "https://realm.com/my_realm_filter/{id}", + "id": 1 + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "deprecated": true, + "description": "Legacy event type that is no longer sent to clients. Previously, sent\nto all users in a Zulip organization when the set of configured\n[linkifiers](/help/add-a-custom-linkifier) for the organization was\nchanged.\n\n**Changes**: Prior to Zulip 7.0 (feature level 176), this event type\nwas sent to clients.\n\n**Deprecated** in Zulip 4.0 (feature level 54), and replaced by the\n`realm_linkifiers` event type, which has a clearer name and format.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_filters"] + } + ] + }, + "realm_filters": { + "type": "array", + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "integer" + }, + { + "type": "string" + } + ] + } + }, + "description": "An array of tuples, where each tuple described a linkifier. The first\nelement of the tuple was a string regex pattern which represented the\npattern to be linkified on matching, for example `\"#(?P[123])\"`.\nThe second element was the URL format string that the pattern should be\nlinkified with. A URL format string for the above example would be\n`\"https://realm.com/my_realm_filter/%(id)s\"`. And the third element\nwas the ID of the realm filter.\n" + } + }, + "example": { + "type": "realm_filters", + "realm_filters": [], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the\nset of configured [code playgrounds](/help/code-blocks#code-playgrounds)\nfor the organization has changed.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_playgrounds"] + } + ] + }, + "realm_playgrounds": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains\ndata about a single playground entry.\n", + "items": { + "$ref": "#/components/schemas/RealmPlayground" + } + } + }, + "example": { + "type": "realm_playgrounds", + "realm_playgrounds": [ + { + "id": 1, + "name": "Python playground", + "pygments_language": "Python", + "url_template": "https://python.example.com" + } + ], + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when\na [custom emoji](/help/custom-emoji) has been updated,\ntypically when a new emoji has been added or an old one\nhas been deactivated. The event contains all custom emoji\nconfigured for the organization, not just the updated\ncustom emoji.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_emoji"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "realm_emoji": { + "type": "object", + "description": "An object in which each key describes a realm emoji.\n", + "additionalProperties": { + "$ref": "#/components/schemas/RealmEmoji" + } + } + }, + "example": { + "type": "realm_emoji", + "op": "update", + "realm_emoji": { + "2": { + "id": "2", + "name": "my_emoji", + "source_url": "/user_avatars/2/emoji/images/2.png", + "deactivated": true, + "author_id": 11 + }, + "1": { + "id": "1", + "name": "green_tick", + "source_url": "/user_avatars/2/emoji/images/1.png", + "deactivated": false, + "author_id": 11 + } + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_domains"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "realm_domain": { + "$ref": "#/components/schemas/RealmDomain" + } + }, + "example": { + "type": "realm_domains", + "op": "add", + "realm_domain": { + "domain": "zulip.org", + "allow_subdomains": false + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_domains"] + } + ] + }, + "op": { + "type": "string", + "enum": ["change"] + }, + "realm_domain": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of the edited domain.\n", + "properties": { + "domain": { + "type": "string", + "description": "The domain whose settings have changed.\n" + }, + "allow_subdomains": { + "type": "boolean", + "description": "Whether subdomains are allowed for this domain.\n" + } + } + } + }, + "example": { + "type": "realm_domains", + "op": "change", + "realm_domain": { + "domain": "zulip.org", + "allow_subdomains": true + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_domains"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "domain": { + "type": "string", + "description": "The domain to be removed.\n" + } + }, + "example": { + "type": "realm_domains", + "op": "remove", + "domain": "zulip.org", + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to the user who requested a\n[data export](/help/export-your-organization)\nwhen the status of the data export changes.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_export"] + } + ] + }, + "exports": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains\ndetails about a data export of the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), `export_type`\nparameter was not present as only public data export was supported via API.\n", + "items": { + "$ref": "#/components/schemas/RealmExport" + } + } + }, + "example": { + "type": "realm_export", + "exports": [ + { + "id": 107, + "export_time": 1594825443.656797, + "acting_user_id": 10, + "export_url": null, + "deleted_timestamp": null, + "failed_timestamp": 1594825444.436336, + "pending": false, + "export_type": 1 + } + ], + "id": 1 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to administrators when the [data export\nconsent][help-export-consent] status for a user changes, whether due\nto a user changing their consent preferences or a user being created\nor reactivated (since user creation/activation events do not contain\nthese data).\n\n[help-export-consent]: /help/export-your-organization#configure-whether-administrators-can-export-your-private-data\n\n**Changes**: New in Zulip 10.0 (feature level 312). Previously,\nthere was not event available to administrators with these data.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_export_consent"] + } + ] + }, + "user_id": { + "type": "integer", + "description": "The ID of the user whose setting was changed.\n" + }, + "consented": { + "type": "boolean", + "description": "Whether the user has consented for their private data export.\n" + } + }, + "example": { + "type": "realm_export_consent", + "user_id": 1, + "consented": true + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to users who can administer a newly created bot\nuser. Clients will also receive a `realm_user` event that\ncontains basic details (but not the API key).\n\nThe `realm_user` events are sufficient for clients that\nonly need to interact with the bot; this `realm_bot` event\ntype is relevant only for administering bots.\n\nOnly organization administrators and the user who owns the bot will\nreceive this event.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_bot"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "bot": { + "$ref": "#/components/schemas/Bot" + } + }, + "example": { + "type": "realm_bot", + "op": "add", + "bot": { + "email": "test-bot@zulip.testserver", + "user_id": 36, + "full_name": "Foo Bot", + "bot_type": 1, + "is_active": true, + "api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK", + "default_sending_stream": null, + "default_events_register_stream": null, + "default_all_public_streams": false, + "avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1", + "services": [], + "owner_id": 10 + }, + "id": 1 + } + }, + { + "type": "object", + "description": "Event sent to users who can administer a bot user when the bot is\nconfigured. Clients may also receive a `realm_user` event that\nfor changes in public data about the bot (name, etc.).\n\nThe `realm_user` events are sufficient for clients that\nonly need to interact with the bot; this `realm_bot` event\ntype is relevant only for administering bots.\n\nOnly organization administrators and the user who owns the bot will\nreceive this event.\n", + "additionalProperties": false, + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_bot"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "bot": { + "allOf": [ + { + "description": "Object containing details about the changed bot.\nIt contains two properties: the user ID of the bot and\nthe property to be changed. The changed property is one\nof the remaining properties listed below.\n" + }, + { + "$ref": "#/components/schemas/BasicBot" + } + ] + } + }, + "example": { + "type": "realm_bot", + "op": "update", + "bot": { + "user_id": 37, + "services": [ + { + "base_url": "http://hostname.domain2.com", + "interface": 2, + "token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw" + } + ] + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when a bot has been deactivated.\n\n**Changes**: Deprecated and no longer sent since Zulip 8.0 (feature level 222).\n\nPreviously, this event was sent to all users in a Zulip organization when a\nbot was deactivated.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_bot"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "bot": { + "type": "object", + "description": "Object containing details about the deactivated bot.\n", + "additionalProperties": false, + "properties": { + "user_id": { + "type": "integer", + "description": "The user ID of the deactivated bot.\n" + }, + "full_name": { + "type": "string", + "description": "The full name of the deactivated bot.\n" + } + } + } + }, + "example": { + "type": "realm_bot", + "op": "remove", + "bot": { + "user_id": 35, + "full_name": "Foo Bot" + }, + "id": 1 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users when a bot has been deactivated.\nNote that this is very similar to the bot_remove event\nand one of them will be removed soon.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_bot"] + } + ] + }, + "op": { + "type": "string", + "enum": ["delete"] + }, + "bot": { + "type": "object", + "description": "Object containing details about the deactivated bot.\n", + "additionalProperties": false, + "properties": { + "user_id": { + "type": "integer", + "description": "The user ID of the deactivated bot.\n" + } + } + } + }, + "example": { + "type": "realm_bot", + "op": "delete", + "bot": { + "user_id": 35 + }, + "id": 1 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "The simpler of two possible event types sent to all users\nin a Zulip organization when the configuration of the\norganization (realm) has changed.\n\nOften individual settings are migrated from this format to\nthe [realm/update_dict](#realm-update_dict) event format when additional realm\nsettings are added whose values are coupled to each other\nin some way. The specific values supported by this event\ntype are documented in the [realm/update_dict](#realm-update_dict)\ndocumentation.\n\nA correct client implementation should convert these\nevents into the corresponding [realm/update_dict](#realm-update_dict)\nevent and then process that.\n\n**Changes**: Removed `extra_data` optional property in Zulip 10.0\n(feature level 306). The `extra_data` used to include an\n`upload_quota` field when changed property was `plan_type`. The\nserver now sends a standard `realm/update_dict` event for plan\nchanges.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "property": { + "type": "string", + "description": "The name of the property that was changed.\n" + }, + "value": { + "description": "The new value of the property.\n", + "oneOf": [ + { + "type": "string" + }, + { + "type": "boolean" + }, + { + "type": "integer", + "nullable": true + } + ] + } + }, + "example": { + "type": "realm", + "op": "update", + "property": "disallow_disposable_email_addresses", + "value": false, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the\norganization (realm) is deactivated. Its main purpose is to\nflush active longpolling connections so clients can immediately\nshow the organization as deactivated.\n\nClients cannot rely on receiving this event, because they will\nno longer be able to authenticate to the Zulip API due to the\ndeactivation, and thus can miss it if they did not have an active\nlongpolling connection at the moment of deactivation.\n\nCorrect handling of realm deactivations requires that clients\nparse authentication errors from GET /events; if that is done\ncorrectly, the client can ignore this event type and rely on its\nhandling of the `GET /events` request it will do immediately\nafter processing this batch of events.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm"] + } + ] + }, + "op": { + "type": "string", + "enum": ["deactivated"] + }, + "realm_id": { + "type": "integer", + "description": "The ID of the deactivated realm.\n" + } + }, + "example": { + "type": "realm", + "op": "deactivated", + "realm_id": 2, + "id": 0 + } + }, + { + "type": "object", + "description": "Event sent to all the users whenever the Zulip server restarts.\n\nSpecifically, this event is sent whenever the Tornado process\nfor the user is restarted; in particular, this will always happen\nwhen the Zulip server is upgraded.\n\nClients should use this event to update their tracking of the\nserver's capabilities, and to decide if they wish to get a new\nevent queue after a server upgrade. Clients doing so must\nimplement a random delay strategy to spread such restarts over 5\nminutes or more to avoid creating a synchronized thundering herd\neffect.\n\n**Changes**: Removed the `immediate` flag, which was only used by\nweb clients in development, in Zulip 9.0 (feature level 240).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["restart"] + } + ] + }, + "zulip_version": { + "type": "string", + "description": "The Zulip version number, in the format where this appears\nin the [server_settings](/api/get-server-settings) and\n[register](/api/register-queue) responses.\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" + }, + "zulip_merge_base": { + "type": "string", + "description": "The Zulip merge base number, in the format where this appears\nin the [server_settings](/api/get-server-settings) and\n[register](/api/register-queue) responses.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" + }, + "zulip_feature_level": { + "type": "integer", + "description": "The [Zulip feature level](/api/changelog) of the server\nafter the restart.\n\nClients should use this to update their tracking of the\nserver's capabilities, and may choose to refetch their state\nand create a new event queue when the API feature level has\nchanged in a way that the client finds significant. Clients\nchoosing to do so must implement a random delay strategy to\nspread such restarts over 5 or more minutes to avoid creating\na synchronized thundering herd effect.\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" + }, + "server_generation": { + "type": "integer", + "description": "The timestamp at which the server started.\n" + } + }, + "additionalProperties": false, + "example": { + "id": 0, + "server_generation": 1619334181, + "type": "restart", + "zulip_feature_level": 57, + "zulip_version": "5.0-dev-1650-gc3fd37755f", + "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c" + } + }, + { + "type": "object", + "description": "An event which signals the official Zulip web/desktop app to update,\nby reloading the page and fetching a new queue; this will generally\nfollow a `restart` event. Clients which do not obtain their code\nfrom the server (e.g. mobile and terminal clients, which store their\ncode locally) should ignore this event.\n\nClients choosing to reload the application must implement a random\ndelay strategy to spread such restarts over 5 or more minutes to\navoid creating a synchronized thundering herd effect.\n\n**Changes**: New in Zulip 9.0 (feature level 240).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["web_reload_client"] + } + ] + }, + "immediate": { + "type": "boolean", + "description": "Whether the client should fetch a new event queue immediately,\nrather than using a backoff strategy to avoid thundering herds.\nA Zulip development server uses this parameter to reload\nclients immediately.\n" + } + }, + "additionalProperties": false, + "example": { + "id": 0, + "type": "web_reload_client", + "immediate": true + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "The more general of two event types that may be used when\nsending an event to all users in a Zulip organization when\nthe configuration of the organization (realm) has changed.\n\nUnlike the simpler [realm/update](#realm-update) event format, this\nevent type supports multiple properties being changed in a\nsingle event.\n\nThis event is also sent when deactivating or reactivating a user\nfor settings set to anonymous user groups which the user is direct\nmember of. When deactivating the user, event is only sent to users\nwho cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when deactivating or reactivating a user.\n\nIn Zulip 7.0 (feature level 163), the realm setting\n`email_address_visibility` was removed. It was replaced by a [user\nsetting](/api/update-settings#parameter-email_address_visibility) with\na [realm user default][user-defaults], with the encoding of different\nvalues preserved. Clients can support all versions by supporting the\ncurrent API and treating every user as having the realm's\n`email_address_visibility` value.\n\n[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update_dict"] + }, + "property": { + "type": "string", + "deprecated": true, + "description": "Always `\"default\"`. Present for backwards-compatibility with older\nclients that predate the `update_dict` event style.\n\n**Deprecated** and will be removed in a future release.\n" + }, + "data": { + "type": "object", + "description": "An object containing the properties that have changed.\n\n**Changes**: In Zulip 10.0 (feature level 316), `edit_topic_policy`\nproperty was removed and replaced by `can_move_messages_between_topics_group`\nrealm setting.\n\nIn Zulip 7.0 (feature level 183), the\n`community_topic_editing_limit_seconds` property was removed.\nIt was documented as potentially returned as a changed property\nin this event, but in fact it was only ever returned in the\n[`POST /register`](/api/register-queue) response.\n\nBefore Zulip 6.0 (feature level 150), on changing any of\n`allow_message_editing`, `message_content_edit_limit_seconds`, or\n`edit_topic_policy` settings, this object included all the three settings\nirrespective of which of these settings were changed. Now, a separate event\nis sent for each changed setting.\n", + "properties": { + "allow_message_editing": { + "type": "boolean", + "description": "Whether this organization's [message edit policy][config-message-editing]\nallows editing the content of messages.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n" + }, + "authentication_methods": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/RealmAuthenticationMethod" + }, + "description": "Dictionary of authentication method keys mapped to dictionaries that\ndescribe the properties of the named authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n\nClients should use this to implement server-settings UI to change which\nmethods are enabled for the organization. For authentication UI itself,\nclients should use the pre-authentication metadata returned by\n[`GET /server_settings`](/api/get-server-settings).\n\n**Changes**: In Zulip 9.0 (feature level 243), the values in this\ndictionary were changed. Previously, the values were a simple boolean\nindicating whether the backend is enabled or not.\n" + }, + "can_access_all_users_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to access all users in the\norganization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 225).\n" + } + ] + }, + "can_create_groups": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create user\ngroups in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 299). Previously\n`user_group_edit_policy` field used to control the permission\nto create user groups.\n" + } + ] + }, + "can_create_bots_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create all types of bot users\nin the organization. See also `can_create_write_only_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" + } + ] + }, + "can_create_write_only_bots_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create bot users that\ncan only send messages in the organization, i.e. incoming webhooks,\nin addition to the users who are present in `can_create_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" + } + ] + }, + "can_create_public_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create public\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 264). Previously\n`realm_create_public_stream_policy` field used to control the\npermission to create public channels.\n" + } + ] + }, + "can_create_private_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create private\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 266). Previously\n`realm_create_private_stream_policy` field used to control the\npermission to create private channels.\n" + } + ] + }, + "can_create_web_public_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create web-public\nchannels in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 280). Previously\n`realm_create_web_public_stream_policy` field used to control\nthe permission to create web-public channels.\n" + } + ] + }, + "can_add_custom_emoji_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add custom emoji in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 307). Previously, this\npermission was controlled by the enum `add_custom_emoji_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n\nBefore Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`\nboolean setting controlled this permission; `true` corresponded to `Admins`,\nand `false` to `Everyone`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_add_subscribers_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add subscribers to channels in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 341). Previously, this\npermission was controlled by the enum `invite_to_stream_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_delete_any_message_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete any message in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 281). Previously, this\npermission was limited to administrators only and was uneditable.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_delete_own_message_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete messages that they have sent in the\norganization.\n\n**Changes**: New in Zulip 10.0 (feature level 291). Previously, this\npermission was controlled by the enum `delete_own_message_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.\n\nBefore Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean\nsetting controlled this permission; `true` corresponded to `Everyone`, and\n`false` to `Admins`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_set_delete_message_policy_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `can_delete_any_message_group`\nand `can_delete_own_message_group` permission settings. Note that the user\nmust be a member of both this group and the `can_administer_channel_group`\nof the channel whose message delete settings they want to change.\n\nOrganization administrators can always change these settings of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_set_topics_policy_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `topics_policy` setting. Note that\nthe user must be a member of both this group and the `can_administer_channel_group`\nof the channel whose `topics_policy` they want to change.\n\nOrganization administrators can always change the `topics_policy` setting of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 392).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_invite_users_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to send email invitations for inviting other users\nto the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 321). Previously, this\npermission was controlled by the enum `invite_to_realm_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nBefore Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean\nsetting controlled this permission; `true` corresponded to `Admins`, and\n`false` to `Members`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_mention_many_users_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using mentions in large\nchannels, even when permitted to do so.\n\n**Changes**: New in Zulip 10.0 (feature level 352). Previously, this\npermission was controlled by the enum `wildcard_mention_policy`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_move_messages_between_channels_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one channel to another\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 310). Previously, this\npermission was controlled by the enum `move_messages_between_streams_policy`.\nValues were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`move_messages_between_streams_policy` enum.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_move_messages_between_topics_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one topic to another\nwithin a channel in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 316). Previously, this\npermission was controlled by the enum `edit_topic_policy`. Values were\n1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`edit_topic_policy` enum.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_resolve_topics_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to [resolve topics](/help/resolve-a-topic)\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 367). Previously, permission to\nresolve topics was controlled by the more general\ncan_move_messages_between_topics_group permission for moving messages.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_manage_all_groups": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + } + ] + }, + "can_manage_billing_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to manage plans and billing in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners\nand users with `is_billing_admin` property set to `true` were allowed to\nmanage plans and billing.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "can_summarize_topics_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to use AI summarization.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + } + ] + }, + "create_multiuse_invite_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to create [reusable invitation\nlinks](/help/invite-new-users#create-a-reusable-invitation-link)\nto the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 209).\n" + } + ] + }, + "default_code_block_language": { + "type": "string", + "description": "The default pygments language code to be used for code blocks in this\norganization. If an empty string, no default has been set.\n\n**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant\nthat both `null` and an empty string could represent that no default was\nset for this realm setting in the [`POST /register`](/api/register-queue)\nresponse. The documentation for both that endpoint and this event\nincorrectly stated that the only representation for no default language\nwas `null`. This event in fact uses the empty string to indicate that no\ndefault has been set in all server versions.\n" + }, + "default_language": { + "type": "string", + "description": "The default language for the organization.\n" + }, + "description": { + "type": "string", + "description": "The description of the organization, used on login and registration pages.\n" + }, + "digest_emails_enabled": { + "type": "boolean", + "description": "Whether the organization has enabled [weekly digest emails](/help/digest-emails).\n" + }, + "digest_weekday": { + "type": "integer", + "description": "The day of the week when the organization will send\nits weekly digest email to inactive users.\n" + }, + "direct_message_initiator_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to start a new direct message conversation\ninvolving other non-bot users. Users who are outside this group and attempt\nto send the first direct message to a given collection of recipient users\nwill receive an error, unless all other recipients are bots or the sender.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "direct_message_permission_group": { + "allOf": [ + { + "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to fully use direct messages. Users outside\nthis group can only send direct messages to conversations where all the\nrecipients are in this group, are bots, or are the sender, ensuring that\nevery direct message conversation will be visible to at least one user in\nthis group.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "disallow_disposable_email_addresses": { + "type": "boolean", + "description": "Whether the organization disallows disposable email\naddresses.\n" + }, + "email_changes_disabled": { + "type": "boolean", + "description": "Whether users are allowed to change their own email address in this\norganization. This is typically disabled for organizations that\nsynchronize accounts from LDAP or a similar corporate database.\n" + }, + "enable_read_receipts": { + "type": "boolean", + "description": "Whether read receipts is enabled in the organization or not.\n\nIf disabled, read receipt data will be unavailable to clients, regardless\nof individual users' personal read receipt settings. See also the\n`send_read_receipts` setting within `realm_user_settings_defaults`.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n" + }, + "emails_restricted_to_domains": { + "type": "boolean", + "description": "Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)\nthis organization are required to have an email\naddress in one of the `realm_domains` configured for the organization.\n" + }, + "enable_guest_user_dm_warning": { + "type": "boolean", + "description": "Whether clients should show a warning when a user is composing\na DM to a guest user in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 348).\n" + }, + "enable_guest_user_indicator": { + "type": "boolean", + "description": "Whether clients should display \"(guest)\" after the names of\nguest users to prominently highlight their status.\n\n**Changes**: New in Zulip 8.0 (feature level 216).\n" + }, + "enable_spectator_access": { + "type": "boolean", + "description": "Whether web-public channels are enabled in this organization.\n\nCan only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`\n[server setting][server-settings] is enabled on the Zulip\nserver. See also the `can_create_web_public_channel_group`\nrealm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 109).\n" + }, + "giphy_rating": { + "type": "integer", + "description": "Maximum rating of the GIFs that will be retrieved from GIPHY.\n\n**Changes**: New in Zulip 4.0 (feature level 55).\n" + }, + "icon_source": { + "type": "string", + "description": "String indicating whether the organization's\n[profile icon](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the organization's icon.\n\n- \"G\" means generated by Gravatar (the default).\n- \"U\" means uploaded by an organization administrator.\n" + }, + "icon_url": { + "type": "string", + "description": "The URL of the organization's [profile icon](/help/create-your-organization-profile).\n" + }, + "inline_image_preview": { + "type": "boolean", + "description": "Whether this organization has been configured to enable\n[previews of linked images](/help/image-video-and-website-previews).\n" + }, + "inline_url_embed_preview": { + "type": "boolean", + "description": "Whether this organization has been configured to enable\n[previews of linked websites](/help/image-video-and-website-previews).\n" + }, + "invite_required": { + "type": "boolean", + "description": "Whether an invitation is required to join this organization.\n" + }, + "jitsi_server_url": { + "type": "string", + "nullable": true, + "description": "The URL of the custom Jitsi Meet server configured in this organization's\nsettings.\n\n`null`, the default, means that the organization is using the should use the\nserver-level configuration, `server_jitsi_server_url`.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only\navailable as a server-level configuration, and required a server restart to\nchange.\n" + }, + "logo_source": { + "type": "string", + "description": "String indicating whether the organization's\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" + }, + "logo_url": { + "type": "string", + "description": "The URL of the organization's wide logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" + }, + "topics_policy": { + "type": "string", + "enum": [ + "allow_empty_topic", + "disable_empty_topic" + ], + "description": "The organization's default policy for sending channel messages to the\n[empty \"general chat\" topic](/help/general-chat-topic).\n\n- `\"allow_empty_topic\"`: Channel messages can be sent to the empty topic.\n- `\"disable_empty_topic\"`: Channel messages cannot be sent to the empty topic.\n\n**Changes**: New in Zulip 11.0 (feature level 392). Previously, this was\ncontrolled by the boolean realm `mandatory_topics` setting, which is now\ndeprecated.\n" + }, + "mandatory_topics": { + "type": "boolean", + "deprecated": true, + "description": "Whether [topics are required](/help/require-topics) for messages in this\norganization.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now\ncontrolled by the realm `topics_policy` setting.\n" + }, + "max_file_upload_size_mib": { + "type": "integer", + "description": "The new maximum file size that can be uploaded to this Zulip organization.\n\n**Changes**: New in Zulip 10.0 (feature level 306). Previously, this field of\nthe core state did not support being updated via the events system, as it was\ntypically hardcoded for a given Zulip installation.\n" + }, + "message_content_allowed_in_email_notifications": { + "type": "boolean", + "description": "Whether notification emails in this organization are allowed to\ncontain Zulip the message content, or simply indicate that a new\nmessage was sent.\n" + }, + "message_content_delete_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Messages sent more than this many seconds ago cannot be deleted\nwith this organization's\n[message deletion policy](/help/restrict-message-editing-and-deletion).\n\nWill not be 0. A `null` value means no limit: messages can be deleted\nregardless of how long ago they were sent.\n\n**Changes**: No limit was represented using the\nspecial value `0` before Zulip 5.0 (feature level 100).\n" + }, + "message_content_edit_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Messages sent more than this many seconds ago cannot be edited\nwith this organization's\n[message edit policy](/help/restrict-message-editing-and-deletion).\n\nWill not be `0`. A `null` value means no limit, so messages can be edited\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: Before Zulip 6.0 (feature level 138), no limit was\nrepresented using the special value `0`.\n" + }, + "message_edit_history_visibility_policy": { + "type": "string", + "description": "Which type of message edit history is configured to allow users to\naccess [message edit history](/help/view-a-messages-edit-history).\n\n- \"all\" = All edit history is visible.\n- \"moves\" = Only moves are visible.\n- \"none\" = No edit history is visible.\n\n**Changes**: New in Zulip 10.0 (feature level 358), replacing the previous\n`allow_edit_history` boolean setting; `true` corresponds to `all`,\nand `false` to `none`.\n" + }, + "moderation_request_channel_id": { + "type": "integer", + "description": "The ID of the private channel to which messages flagged by users for\nmoderation are sent. Moderators can use this channel to review and\nact on reported content.\n\nWill be `-1` if moderation requests are disabled.\n\nClients should check whether moderation requests are disabled to\ndetermine whether to present a \"report message\" feature in their UI\nwithin a given organization.\n\n**Changes**: New in Zulip 10.0 (feature level 331). Previously,\nno \"report message\" features existed in Zulip.\n" + }, + "move_messages_within_stream_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Messages sent more than this many seconds ago cannot be moved within a\nchannel to another topic by users who have permission to do so based on this\norganization's [topic edit policy](/help/restrict-moving-messages). This\nsetting does not affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so message topics can be\nedited regardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time\nlimit was always 72 hours for users who were not administrators or\nmoderators.\n" + }, + "move_messages_between_streams_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Messages sent more than this many seconds ago cannot be moved between\nchannels by users who have permission to do so based on this organization's\n[message move policy](/help/restrict-moving-messages). This setting does\nnot affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so messages can be moved\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was\nno time limit for moving messages between channels for users with permission\nto do so.\n" + }, + "name": { + "type": "string", + "description": "The name of the organization, used in login pages etc.\n" + }, + "name_changes_disabled": { + "type": "boolean", + "description": "Indicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their name\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" + }, + "night_logo_source": { + "type": "string", + "description": "String indicating whether the organization's dark theme\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" + }, + "night_logo_url": { + "type": "string", + "description": "The URL of the organization's dark theme wide-format logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" + }, + "new_stream_announcements_stream_id": { + "type": "integer", + "description": "The ID of the channel to which automated messages announcing the\n[creation of new channels][new-channel-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed `notifications_stream_id`\nto `new_stream_announcements_stream_id`.\n" + }, + "org_type": { + "type": "integer", + "description": "The [organization type](/help/organization-type)\nfor the realm.\n\n- 0 = Unspecified\n- 10 = Business\n- 20 = Open-source project\n- 30 = Education (non-profit)\n- 35 = Education (for-profit)\n- 40 = Research\n- 50 = Event or conference\n- 60 = Non-profit (registered)\n- 70 = Government\n- 80 = Political group\n- 90 = Community\n- 100 = Personal\n- 1000 = Other\n\n**Changes**: New in Zulip 6.0 (feature level 128).\n" + }, + "plan_type": { + "type": "integer", + "description": "The plan type of the organization.\n\n- 1 = Self-hosted organization (SELF_HOSTED)\n- 2 = Zulip Cloud free plan (LIMITED)\n- 3 = Zulip Cloud Standard plan (STANDARD)\n- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)\n" + }, + "presence_disabled": { + "type": "boolean", + "description": "Whether online presence of other users is shown in this\norganization.\n" + }, + "push_notifications_enabled": { + "type": "boolean", + "description": "Whether push notifications are enabled for this organization. Typically\n`true` for Zulip Cloud and self-hosted realms that have a valid\nregistration for the [Mobile push notifications\nservice](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),\nand `false` for self-hosted servers that do not.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\nPreviously, this value was never updated via events.\n" + }, + "push_notifications_enabled_end_timestamp": { + "type": "integer", + "nullable": true, + "description": "If the server expects the realm's push notifications access to end at a\ndefinite time in the future, the time at which this is expected to happen.\nMobile clients should use this field to display warnings to users when the\nindicated timestamp is near.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\n" + }, + "require_e2ee_push_notifications": { + "type": "boolean", + "description": "Whether this realm is configured to disallow sending mobile\npush notifications with message content through the legacy\nmobile push notifications APIs. The new API uses end-to-end\nencryption to protect message content and metadata from\nbeing accessible to the push bouncer service, APNs, and\nFCM. Clients that support the new E2EE API will use it\nautomatically regardless of this setting.\n\nIf `true`, mobile push notifications sent to clients that\nlack support for E2EE push notifications will always have\n\"New message\" as their content. Note that these legacy\nmobile notifications will still contain metadata, which may\ninclude the message's ID, the sender's name, email address,\nand avatar.\n\nIn a future release, once the official mobile apps have\nimplemented fully validated their E2EE protocol support,\nthis setting will become strict, and disable the legacy\nprotocol entirely.\n\n**Changes**: New in Zulip 11.0 (feature level 409). Previously,\nthis behavior was available only via the\n`PUSH_NOTIFICATION_REDACT_CONTENT` global server setting.\n" + }, + "require_unique_names": { + "type": "boolean", + "description": "Indicates whether the organization is configured to require users to have\nunique full names. If true, the server will reject attempts to create a\nnew user, or change the name of an existing user, where doing so would\nlead to two users whose names are identical modulo case and unicode\nnormalization.\n\n**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip\nserver could not be configured to enforce unique names.\n" + }, + "send_welcome_emails": { + "type": "boolean", + "description": "Whether or not this organization is configured to send the standard Zulip\n[welcome emails](/help/disable-welcome-emails) to new users joining the organization.\n" + }, + "signup_announcements_stream_id": { + "type": "integer", + "description": "The ID of the channel to which automated messages announcing\nthat [new users have joined the organization][new-user-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-user-announce]: /help/configure-automated-notices#new-user-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed\n`signup_notifications_stream_id` to `signup_announcements_stream_id`.\n" + }, + "upload_quota_mib": { + "type": "integer", + "nullable": true, + "description": "The new upload quota for the Zulip organization.\n\nIf `null`, there is no limit.\n\n**Changes**: New in Zulip 10.0 (feature level 306). Previously,\nthis was present changed via an `upload_quota` field in `extra_data` property\nof [realm/update](#realm-update) event format for `plan_type` events.\n" + }, + "video_chat_provider": { + "type": "integer", + "description": "The configured [video call provider](/help/configure-call-provider) for the\norganization.\n\n- 0 = None\n- 1 = Jitsi Meet\n- 3 = Zoom (User OAuth integration)\n- 4 = BigBlueButton\n- 5 = Zoom (Server to Server OAuth integration)\n\nNote that only one of the [Zoom integrations][zoom-video-calls] can\nbe configured on a Zulip server.\n\n**Changes**: In Zulip 10.0 (feature level 353), added the Zoom Server\nto Server OAuth option.\n\nIn Zulip 3.0 (feature level 1), added the None option\nto disable video call UI.\n\n[zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom\n" + }, + "waiting_period_threshold": { + "type": "integer", + "description": "Members whose accounts have been created at least this many days ago\nwill be treated as [full members][calc-full-member]\nfor the purpose of settings that restrict access to new members.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "want_advertise_in_communities_directory": { + "type": "boolean", + "description": "Whether the organization has given permission to be advertised in the\nZulip [communities directory](/help/communities-directory).\n\n**Changes**: New in Zulip 6.0 (feature level 129).\n" + }, + "welcome_message_custom_text": { + "type": "string", + "description": "This organization's configured custom message for Welcome Bot\nto send to new user accounts, in Zulip Markdown format.\n\nMaximum length is 8000 characters.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n" + }, + "zulip_update_announcements_stream_id": { + "type": "integer", + "description": "The ID of the channel to which automated messages announcing\nnew features or other end-user updates about the Zulip software are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n**Changes**: New in Zulip 9.0 (feature level 242).\n" + } + }, + "additionalProperties": false + } + }, + "example": { + "type": "realm", + "op": "update_dict", + "property": "default", + "data": { + "message_content_edit_limit_seconds": 600 + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to all users in a Zulip organization when the\n[default settings for new users][new-user-defaults]\nof the organization (realm) have changed.\n\n[new-user-defaults]: /help/configure-default-new-user-settings\n\nSee [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)\nfor details on possible properties.\n\n**Changes**: New in Zulip 5.0 (feature level 95).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["realm_user_settings_defaults"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "property": { + "type": "string", + "description": "The name of the property that was changed.\n" + }, + "value": { + "description": "The new value of the property.\n", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "integer" + }, + { + "type": "string" + } + ] + } + }, + "example": { + "type": "realm_user_settings_defaults", + "op": "update", + "property": "left_side_userlist", + "value": false, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details of newly created drafts.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["drafts"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "drafts": { + "type": "array", + "description": "An array containing objects for the newly created drafts.\n", + "items": { + "$ref": "#/components/schemas/Draft" + } + } + }, + "example": { + "type": "drafts", + "op": "add", + "drafts": [ + { + "id": 17, + "type": "private", + "to": [6], + "topic": "", + "content": "Hello there!", + "timestamp": 15954790200 + } + ] + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details for an edited draft.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["drafts"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "draft": { + "$ref": "#/components/schemas/Draft" + } + }, + "example": { + "type": "drafts", + "op": "update", + "draft": { + "id": 17, + "type": "private", + "to": [6, 7, 8, 9, 10], + "topic": "", + "content": "Hello everyone!", + "timestamp": 15954790200 + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing the ID of a deleted draft.\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["drafts"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "draft_id": { + "type": "integer", + "description": "The ID of the draft that was just deleted.\n" + } + }, + "example": { + "type": "drafts", + "op": "remove", + "draft_id": 17 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details of a newly configured navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["navigation_view"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "navigation_view": { + "$ref": "#/components/schemas/NavigationView" + } + }, + "example": { + "type": "navigation_view", + "op": "add", + "navigation_view": { + "fragment": "narrow/is/alerted", + "is_pinned": true, + "name": "Alert Words" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details of an update to an existing navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["navigation_view"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "fragment": { + "type": "string", + "description": "The unique URL hash of the navigation view being updated.\n" + }, + "data": { + "type": "object", + "additionalProperties": false, + "description": "A dictionary containing the updated properties of the navigation view.\n", + "properties": { + "name": { + "type": "string", + "nullable": true, + "description": "The user-facing name for custom navigation views. Omit this field for built-in views.\n" + }, + "is_pinned": { + "type": "boolean", + "nullable": true, + "description": "Determines whether the view is pinned (true) or hidden in the menu (false).\n" + } + } + } + }, + "example": { + "type": "navigation_view", + "op": "update", + "fragment": "narrow/is/alerted", + "data": { + "is_pinned": false + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing the fragment of a deleted navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["navigation_view"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "fragment": { + "type": "string", + "description": "The unique URL hash of the navigation view that was just deleted.\n" + } + }, + "example": { + "type": "navigation_view", + "op": "remove", + "fragment": "narrow/is/mentioned" + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details of a newly created saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["saved_snippets"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "saved_snippet": { + "$ref": "#/components/schemas/SavedSnippet" + } + }, + "example": { + "type": "saved_snippets", + "op": "add", + "saved_snippet": { + "id": 1, + "title": "Example", + "content": "Welcome to the organization.", + "date_created": 1681662420 + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing details of the edited saved snippet.\n\nClients should update the existing saved snippet with the\nID provided in the `saved_snippet` object.\n\n**Changes**: New in Zulip 10.0 (feature level 368).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["saved_snippets"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "saved_snippet": { + "$ref": "#/components/schemas/SavedSnippet" + } + }, + "example": { + "type": "saved_snippets", + "op": "update", + "saved_snippet": { + "id": 1, + "title": "Example", + "content": "Welcome to the organization.", + "date_created": 1681662420 + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event containing the ID of a deleted saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["saved_snippets"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "saved_snippet_id": { + "type": "integer", + "description": "The ID of the saved snippet that was just deleted.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" + } + }, + "example": { + "type": "saved_snippets", + "op": "remove", + "saved_snippet_id": 17 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when a reminder is scheduled.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["reminders"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "reminders": { + "type": "array", + "description": "An array of objects containing details of the newly created\nreminders.\n", + "items": { + "$ref": "#/components/schemas/Reminder" + } + } + }, + "example": { + "type": "reminders", + "op": "add", + "reminders": [ + { + "reminder_id": 17, + "type": "private", + "to": [6], + "content": "Hello there!", + "rendered_content": "

Hello there!

", + "scheduled_delivery_timestamp": 1681662420, + "failed": false, + "reminder_target_message_id": 42 + } + ] + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when a reminder\nis deleted.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["reminders"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "reminder_id": { + "type": "integer", + "description": "The ID of the reminder that was deleted.\n" + } + }, + "example": { + "type": "reminders", + "op": "remove", + "reminder_id": 17 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when scheduled messages\nare created.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["scheduled_messages"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "scheduled_messages": { + "type": "array", + "description": "An array of objects containing details of the newly created\nscheduled messages.\n", + "items": { + "$ref": "#/components/schemas/ScheduledMessage" + } + } + }, + "example": { + "type": "scheduled_messages", + "op": "add", + "scheduled_messages": [ + { + "scheduled_message_id": 17, + "type": "private", + "to": [6], + "content": "Hello there!", + "rendered_content": "

Hello there!

", + "scheduled_delivery_timestamp": 1681662420, + "failed": false + } + ] + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when a scheduled message\nis edited.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["scheduled_messages"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "scheduled_message": { + "$ref": "#/components/schemas/ScheduledMessage" + } + }, + "example": { + "type": "scheduled_messages", + "op": "update", + "scheduled_message": { + "scheduled_message_id": 17, + "type": "private", + "to": [6], + "content": "Hello there!", + "rendered_content": "

Hello there!

", + "scheduled_delivery_timestamp": 1681662420, + "failed": false + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to a user's clients when a scheduled message\nis deleted.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["scheduled_messages"] + } + ] + }, + "op": { + "type": "string", + "enum": ["remove"] + }, + "scheduled_message_id": { + "type": "integer", + "description": "The ID of the scheduled message that was deleted.\n" + } + }, + "example": { + "type": "scheduled_messages", + "op": "remove", + "scheduled_message_id": 17 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to users in an organization when a channel folder is created.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["channel_folder"] + } + ] + }, + "op": { + "type": "string", + "enum": ["add"] + }, + "channel_folder": { + "$ref": "#/components/schemas/ChannelFolder" + } + }, + "example": { + "type": "channel_folder", + "op": "add", + "channel_folder": { + "name": "fronted", + "creator_id": 9, + "date_created": 1717484476, + "description": "Channels for frontend discussions", + "rendered_description": "

Channels for frontend discussions

", + "order": 1, + "id": 2, + "is_archived": false + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to users in an organization when a channel folder is updated.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["channel_folder"] + } + ] + }, + "op": { + "type": "string", + "enum": ["update"] + }, + "channel_folder_id": { + "type": "number", + "description": "ID of the updated channel folder.\n" + }, + "data": { + "type": "object", + "additionalProperties": false, + "description": "Dictionary containing the changed details of the channel folder.\n", + "properties": { + "name": { + "type": "string", + "description": "The new name of the channel folder. Only present if the channel\nfolder's name changed.\n" + }, + "description": { + "type": "string", + "description": "The new description of the channel folder. Only present if the\ndescription changed.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "rendered_description": { + "type": "string", + "description": "The new rendered description of the channel folder. Only present\nif the description changed.\n" + }, + "is_archived": { + "type": "boolean", + "description": "Whether the channel folder is archived or not. Only present if\nthe channel folder is archived or unarchived.\n" + } + } + } + }, + "example": { + "type": "channel_folder", + "op": "update", + "data": { + "name": "New frontend" + }, + "id": 0 + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "Event sent to users in an organization when channel folders are reordered.\n\n**Changes**: New in Zulip 11.0 (feature level 418).\n", + "properties": { + "id": { + "$ref": "#/components/schemas/EventIdSchema" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EventTypeSchema" + }, + { + "enum": ["channel_folder"] + } + ] + }, + "op": { + "type": "string", + "enum": ["reorder"] + }, + "order": { + "type": "array", + "description": "A list of channel folder IDs representing the new order.\n", + "items": { + "type": "integer" + } + } + }, + "example": { + "type": "channel_folder", + "op": "reorder", + "order": [3, 1, 2], + "id": 0 + } + } + ] + } + }, + "queue_id": { + "type": "string", + "description": "The ID of the registered queue.\n" + } + }, + "example": { + "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", + "events": [ + { + "id": 0, + "message": { + "avatar_url": "https://url/for/othello-bots/avatar", + "client": "website", + "content": "I come not, friends, to steal away your hearts.", + "content_type": "text/x-markdown", + "display_recipient": "Denmark", + "id": 12345678, + "recipient_id": 12314, + "sender_email": "othello-bot@example.com", + "sender_full_name": "Othello Bot", + "sender_id": 13215, + "sender_realm_str": "example", + "topic_links": [], + "timestamp": 1375978403, + "type": "stream" + }, + "type": "message" + }, + { + "id": 1, + "message": { + "avatar_url": "https://url/for/othello-bots/avatar", + "client": "website", + "content": "With mirth and laughter let old wrinkles come.", + "content_type": "text/x-markdown", + "display_recipient": [ + { + "email": "hamlet@example.com", + "full_name": "Hamlet of Denmark", + "id": 31572 + } + ], + "id": 12345679, + "recipient_id": 18391, + "sender_email": "othello-bot@example.com", + "sender_full_name": "Othello Bot", + "sender_id": 13215, + "sender_realm_str": "example", + "subject": "", + "topic_links": [], + "timestamp": 1375978404, + "type": "private" + }, + "type": "message" + } + ], + "msg": "", + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/BadEventQueueIdError" + }, + { + "description": "#### BAD_EVENT_QUEUE_ID errors\n\nThis error occurs if the target event queue has been garbage collected.\nA compliant client will handle this error by re-initializing itself\n(e.g. a Zulip web app browser window will reload in this case).\n\nSee [the /register endpoint docs](/api/register-queue) for details on how to\nhandle these correctly.\n\nThe following is the error response in such case:\n" + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "delete-queue", + "summary": "Delete an event queue", + "tags": ["real_time_events"], + "description": "Delete a previously registered queue.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "queue_id": { + "description": "The ID of an event queue that was previously registered via\n`POST /api/v1/register` (see [Register a queue](/api/register-queue)).\n", + "type": "string", + "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8" + } + }, + "required": ["queue_id"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/BadEventQueueIdError" + }, + { + "description": "A typical JSON response for when the `queue_id` is non-existent or the\nassociated queue has already been deleted:\n" + } + ] + } + } + } + } + } + } + }, + "/get_stream_id": { + "get": { + "operationId": "get-stream-id", + "summary": "Get channel ID", + "tags": ["channels"], + "description": "Get the unique ID of a given channel.\n", + "parameters": [ + { + "name": "stream", + "in": "query", + "description": "The name of the channel to access.\n", + "schema": { + "type": "string" + }, + "example": "Denmark", + "required": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "stream_id": { + "type": "integer", + "description": "The ID of the given channel.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "stream_id": 15 + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid channel name 'nonexistent'", + "result": "error" + }, + "description": "An example JSON response for when the supplied channel does not exist:\n" + } + ] + } + } + } + } + } + } + }, + "/mark_all_as_read": { + "post": { + "deprecated": true, + "operationId": "mark-all-as-read", + "summary": "Mark all messages as read", + "tags": ["messages"], + "description": "Marks all of the current user's unread messages as read.\n\nBecause this endpoint marks messages as read in batches, it is possible\nfor the request to time out after only marking some messages as read.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages were marked as read, then the success response\nwill return `\"complete\": true`.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n\nBefore Zulip 8.0 (feature level 211), if the server's\nprocessing was interrupted by a timeout, but some messages were marked\nas read, then it would return `\"result\": \"partially_completed\"`, along\nwith a `code` field for an error string, in the success response to\nindicate that there was a timeout and that the client should repeat the\nrequest.\n\nBefore Zulip 6.0 (feature level 153), this request did a single atomic\noperation, which could time out with 10,000s of unread messages to mark\nas read. As of this feature level, messages are marked as read in\nbatches, starting with the newest messages, so that progress is made\neven if the request times out. And, instead of returning an error when\nthe request times out and some messages have been marked as read, a\nsuccess response with `\"result\": \"partially_completed\"` is returned.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": ["complete"], + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "complete": { + "type": "boolean", + "description": "Whether all unread messages were marked as read.\n\nWill be `false` if the request successfully marked\nsome, but not all, messages as read.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "complete": true + } + } + ] + } + } + } + } + } + } + }, + "/mark_stream_as_read": { + "post": { + "deprecated": true, + "operationId": "mark-stream-as-read", + "summary": "Mark messages in a channel as read", + "tags": ["messages"], + "description": "Mark all the unread messages in a channel as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the channel to access.\n", + "type": "integer", + "example": 43 + } + }, + "required": ["stream_id"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/mark_topic_as_read": { + "post": { + "deprecated": true, + "operationId": "mark-topic-as-read", + "summary": "Mark messages in a topic as read", + "tags": ["messages"], + "description": "Mark all the unread messages in a topic as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the channel to access.\n", + "type": "integer", + "example": 43 + }, + "topic_name": { + "description": "The name of the topic whose messages should be marked as read.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", + "type": "string", + "example": "new coffee machine" + } + }, + "required": ["stream_id", "topic_name"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/attachments": { + "get": { + "operationId": "get-attachments", + "summary": "Get attachments", + "tags": ["users"], + "description": "Fetch metadata on files uploaded by the requesting user.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "attachments": { + "type": "array", + "description": "A list of `attachment` objects, each containing\ndetails about a file uploaded by the user.\n", + "items": { + "$ref": "#/components/schemas/Attachment" + } + }, + "upload_space_used": { + "type": "integer", + "description": "The total size of all files uploaded by users in the organization,\nin bytes.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "attachments": [ + { + "id": 1, + "name": "166050.jpg", + "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg", + "size": 571946, + "create_time": 1588145417000, + "messages": [ + { + "id": 102, + "date_sent": 1588145424000 + }, + { + "id": 103, + "date_sent": 1588145448000 + } + ] + } + ], + "upload_space_used": 571946 + } + } + ] + } + } + } + } + } + } + }, + "/attachments/{attachment_id}": { + "delete": { + "operationId": "remove-attachment", + "summary": "Delete an attachment", + "tags": ["users"], + "description": "Delete an uploaded file given its attachment ID.\n\nNote that uploaded files that have been referenced in at least\none message are automatically deleted once the last message\ncontaining a link to them is deleted (whether directly or via\na [message retention policy](/help/message-retention-policy)).\n\nUploaded files that are never used in a message are\nautomatically deleted a few weeks after being uploaded.\n\nAttachment IDs can be contained from [GET /attachments](/api/get-attachments).\n", + "parameters": [ + { + "name": "attachment_id", + "in": "path", + "description": "The ID of the attachment to be deleted.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid attachment", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for when the `attachment_id` is invalid\n" + } + ] + } + ] + } + } + } + }, + "401": { + "description": "Error.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "UNAUTHORIZED", + "result": "error", + "msg": "Not logged in: API authentication or user session required" + }, + "description": "A typical failed JSON response for when the user is not logged in:\n" + } + ] + } + } + } + } + } + } + }, + "/drafts": { + "get": { + "operationId": "get-drafts", + "tags": ["drafts"], + "summary": "Get drafts", + "description": "Fetch all drafts for the current user.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "count": { + "type": "integer", + "description": "The number of drafts the user currently has. Also the\nnumber of drafts returned under \"drafts\".\n", + "example": 3 + }, + "drafts": { + "type": "array", + "description": "Returns all of the current user's drafts, in order of last edit time\n(with the most recently edited draft appearing first).\n", + "items": { + "$ref": "#/components/schemas/Draft" + } + } + }, + "example": { + "result": "success", + "msg": "", + "count": 3, + "drafts": [ + { + "id": 1, + "type": "stream", + "to": [3], + "topic": "sync drafts", + "content": "Let's add backend support for syncing drafts.", + "timestamp": 1595479019 + }, + { + "id": 2, + "type": "private", + "to": [4], + "topic": "", + "content": "What if we made it possible to sync drafts in Zulip?", + "timestamp": 1595479019 + }, + { + "id": 3, + "type": "private", + "to": [4, 10], + "topic": "", + "content": "What if we made it possible to sync drafts in Zulip?", + "timestamp": 1595479019 + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "create-drafts", + "tags": ["drafts"], + "summary": "Create drafts", + "description": "Create one or more drafts on the server. These drafts will be automatically\nsynchronized to other clients via `drafts` events.\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "drafts": { + "description": "A JSON-encoded list of containing new draft objects.\n", + "type": "array", + "items": { + "$ref": "#/components/schemas/Draft" + }, + "example": [ + { + "type": "stream", + "to": [1], + "topic": "questions", + "content": "What are the contribution guidelines for this project?", + "timestamp": 1595479019 + } + ] + } + } + }, + "encoding": { + "drafts": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "ids": { + "type": "array", + "description": "An array of the IDs for the drafts that were just created in the same\norder as they were submitted.\n", + "items": { + "type": "integer" + } + } + }, + "example": { + "result": "success", + "msg": "", + "ids": [1, 2, 3] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "JSON response for when a draft targeted towards a channel does not specify\nexactly one channel ID:\n", + "example": { + "code": "BAD_REQUEST", + "msg": "Must specify exactly 1 channel ID for channel messages", + "result": "error" + } + } + ] + } + } + } + } + } + } + }, + "/drafts/{draft_id}": { + "patch": { + "operationId": "edit-draft", + "tags": ["drafts"], + "summary": "Edit a draft", + "description": "Edit a draft on the server. The edit will be automatically\nsynchronized to other clients via `drafts` events.\n", + "parameters": [ + { + "name": "draft_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the draft to be edited.\n", + "required": true, + "example": 2 + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "draft": { + "allOf": [ + { + "$ref": "#/components/schemas/Draft" + }, + { + "description": "A JSON-encoded object containing a replacement draft object for this ID.\n", + "example": { + "type": "stream", + "to": [1], + "topic": "questions", + "content": "how tough is a Lamy Safari?", + "timestamp": 1595479019 + } + } + ] + } + }, + "required": ["draft"] + }, + "encoding": { + "draft": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no draft exists with\nthe provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Draft does not exist" + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "delete-draft", + "tags": ["drafts"], + "summary": "Delete a draft", + "description": "Delete a single draft from the server. The deletion will be automatically\nsynchronized to other clients via a `drafts` event.\n", + "parameters": [ + { + "name": "draft_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the draft you want to delete.\n", + "required": true, + "example": 1 + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no draft exists with\nthe provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Draft does not exist" + } + } + ] + } + } + } + } + } + } + }, + "/navigation_views": { + "get": { + "operationId": "get-navigation-views", + "tags": ["navigation_views"], + "summary": "Get all navigation views", + "description": "Fetch all configured custom navigation views for the current user.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "navigation_views": { + "type": "array", + "description": "An array of dictionaries containing the user's navigation views.\n", + "items": { + "$ref": "#/components/schemas/NavigationView" + } + } + }, + "example": { + "result": "success", + "msg": "", + "navigation_views": [ + { + "fragment": "narrow/is/alerted", + "is_pinned": false, + "name": "Alert Words" + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "add-navigation-view", + "tags": ["navigation_views"], + "summary": "Add a navigation view", + "description": "Adds a new custom left sidebar navigation view configuration\nfor the current user.\n\nThis can be used both to configure built-in navigation views,\nor to add new navigation views.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/NavigationView" + } + } + } + }, + "responses": { + "200": { + "description": "Request succeeded.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {} + }, + "example": { + "result": "success", + "msg": "" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CodedError" + }, + "examples": { + "invalid_parameters": { + "value": { + "code": "BAD_REQUEST", + "msg": "fragment cannot be blank", + "result": "error" + } + } + } + } + } + } + } + } + }, + "/navigation_views/{fragment}": { + "patch": { + "operationId": "edit-navigation-view", + "tags": ["navigation_views"], + "summary": "Update the navigation view", + "description": "Update the details of an existing configured navigation view,\nsuch as its name or whether it's pinned.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "parameters": [ + { + "name": "fragment", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique URL hash of the navigation view to be updated.\n\nThis also serves as the identifier for the navigation view.\n", + "example": "narrow/is/alerted" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "is_pinned": { + "type": "boolean", + "description": "Determines whether the view is pinned (true) or hidden in\nthe menu (false).\n", + "example": true + }, + "name": { + "type": "string", + "description": "The user-facing name for custom navigation views. Omit this\nfield for built-in views.\n", + "example": "Watched Phrases" + } + }, + "anyOf": [ + { + "required": ["is_pinned"] + }, + { + "required": ["name"] + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {} + }, + "example": { + "result": "success", + "msg": "" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Built-in views cannot have a custom name", + "result": "error" + } + } + ], + "description": "A typical failed JSON response for invalid parameters.\n" + } + } + } + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response when no navigation view\nexists with the provided fragment:\n", + "example": { + "code": "NOT_FOUND", + "result": "error", + "msg": "Navigation view does not exist." + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "remove-navigation-view", + "tags": ["navigation_views"], + "summary": "Remove a navigation view", + "description": "Remove a navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "parameters": [ + { + "name": "fragment", + "in": "path", + "schema": { + "type": "string" + }, + "description": "The unique URL hash of the navigation view to be removed.\n\nThis also serves as the identifier for the navigation view.\n", + "example": "narrow/is/alerted", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no navigation\nview exists with the provided fragment:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Navigation view does not exist." + } + } + ] + } + } + } + } + } + } + }, + "/saved_snippets": { + "get": { + "operationId": "get-saved-snippets", + "tags": ["drafts"], + "summary": "Get all saved snippets", + "description": "Fetch all the saved snippets for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "saved_snippets": { + "type": "array", + "description": "An array of dictionaries containing data on all of the current user's\nsaved snippets.\n", + "items": { + "$ref": "#/components/schemas/SavedSnippet" + } + } + }, + "example": { + "result": "success", + "msg": "", + "saved_snippets": [ + { + "id": 1, + "title": "Example", + "content": "Welcome to the organization.", + "date_created": 1681662420 + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "create-saved-snippet", + "tags": ["drafts"], + "summary": "Create a saved snippet", + "description": "Create a new saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The title of the saved snippet.\n", + "example": "Example title" + }, + "content": { + "type": "string", + "description": "The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n", + "example": "Welcome to the organization." + } + }, + "required": ["title", "content"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "saved_snippet_id": { + "type": "integer", + "description": "The unique ID of the saved snippet created.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "saved_snippet_id": 1 + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Title cannot be empty.", + "result": "error" + }, + "description": "A typical failed JSON response for when either title or content is\nempty:\n" + } + ] + } + } + } + } + } + } + }, + "/saved_snippets/{saved_snippet_id}": { + "patch": { + "operationId": "edit-saved-snippet", + "tags": ["drafts"], + "summary": "Edit a saved snippet", + "description": "Edit a saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 368).\n", + "parameters": [ + { + "name": "saved_snippet_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the saved snippet to edit.\n", + "required": true, + "example": 3 + } + ], + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The title of the saved snippet.\n", + "example": "Welcome message" + }, + "content": { + "type": "string", + "description": "The content of the saved snippet in the original [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n", + "example": "Welcome to the organization." + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no saved snippet exists\nwith the provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Saved snippet does not exist." + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "delete-saved-snippet", + "tags": ["drafts"], + "summary": "Delete a saved snippet", + "description": "Delete a saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", + "parameters": [ + { + "name": "saved_snippet_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the saved snippet to delete.\n", + "required": true, + "example": 2 + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no saved snippet exists\nwith the provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Saved snippet does not exist." + } + } + ] + } + } + } + } + } + } + }, + "/reminders": { + "get": { + "operationId": "get-reminders", + "tags": ["reminders"], + "summary": "Get reminders", + "description": "Fetch all [reminders](/help/schedule-a-reminder) for the\ncurrent user.\n\nReminders are messages the user has scheduled to be sent in the\nfuture to themself.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "reminders": { + "type": "array", + "description": "Returns all of the current user's undelivered reminders,\nordered by `scheduled_delivery_timestamp` (ascending).\n", + "items": { + "$ref": "#/components/schemas/Reminder" + } + } + }, + "example": { + "result": "success", + "msg": "", + "reminders": [ + { + "reminder_id": 27, + "to": [6], + "type": "private", + "content": "Hi", + "rendered_content": "

Hi

", + "scheduled_delivery_timestamp": 1681662420, + "failed": false, + "reminder_target_message_id": 42 + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "create-message-reminder", + "tags": ["reminders"], + "summary": "Create a message reminder", + "description": "Schedule a reminder to be sent to the current user at the specified time. The reminder will link the relevant message.\n\n**Changes**: New in Zulip 11.0 (feature level 381).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "message_id": { + "description": "The ID of the previously sent message to reference in the reminder message.\n", + "type": "integer", + "example": 1 + }, + "scheduled_delivery_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the reminder will be sent,\nin UTC seconds.\n", + "example": 5681662420 + }, + "note": { + "type": "string", + "description": "A note associated with the reminder shown in the Notification Bot message.\n\n**Changes**: New in Zulip 11.0 (feature level 415).\n", + "example": "This is a reminder note." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "reminder_id": { + "type": "integer", + "description": "Unique ID of the scheduled message reminder.\n" + } + }, + "example": { + "msg": "", + "reminder_id": 42, + "result": "success" + } + } + ] + } + } + } + } + } + } + }, + "/reminders/{reminder_id}": { + "delete": { + "operationId": "delete-reminder", + "tags": ["reminders"], + "summary": "Delete a reminder", + "description": "Delete, and therefore cancel sending, a previously [scheduled\nreminder](/help/schedule-a-reminder).\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", + "parameters": [ + { + "name": "reminder_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the reminder to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", + "required": true, + "example": 1 + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no reminder exists\nwith the provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Reminder does not exist" + } + } + ] + } + } + } + } + } + } + }, + "/scheduled_messages": { + "get": { + "operationId": "get-scheduled-messages", + "tags": ["scheduled_messages"], + "summary": "Get scheduled messages", + "description": "Fetch all [scheduled messages](/help/schedule-a-message) for\nthe current user.\n\nScheduled messages are messages the user has scheduled to be\nsent in the future via the send later feature.\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "scheduled_messages": { + "type": "array", + "description": "Returns all of the current user's undelivered scheduled\nmessages, ordered by `scheduled_delivery_timestamp`\n(ascending).\n", + "items": { + "$ref": "#/components/schemas/ScheduledMessage" + } + } + }, + "example": { + "result": "success", + "msg": "", + "scheduled_messages": [ + { + "scheduled_message_id": 27, + "to": 14, + "type": "stream", + "content": "Hi", + "rendered_content": "

Hi

", + "topic": "Introduction", + "scheduled_delivery_timestamp": 1681662420, + "failed": false + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "create-scheduled-message", + "tags": ["scheduled_messages"], + "summary": "Create a scheduled message", + "description": "Create a new [scheduled message](/help/schedule-a-message).\n\n**Changes**: In Zulip 7.0 (feature level 184), moved support for\n[editing a scheduled message](/api/update-scheduled-message) to a\nseparate API endpoint, which removed the `scheduled_message_id`\nparameter from this endpoint.\n\nNew in Zulip 7.0 (feature level 179).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of scheduled message to be sent. `\"direct\"` for a direct\nmessage and `\"stream\"` or `\"channel\"` for a channel message.\n\nNote that, while `\"private\"` is supported for scheduling direct\nmessages, clients are encouraged to use to the modern convention of\n`\"direct\"` to indicate this message type, because support for\n`\"private\"` may eventually be removed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate the type of a channel\nmessage.\n", + "type": "string", + "enum": ["direct", "channel", "stream", "private"], + "example": "direct" + }, + "to": { + "description": "The scheduled message's tentative target audience.\n\nFor channel messages, the integer ID of the channel.\nFor direct messages, a list containing integer user IDs.\n", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "integer" + }, + "minLength": 1 + } + ], + "example": [9, 10] + }, + "content": { + "$ref": "#/components/schemas/RequiredContent" + }, + "topic": { + "description": "The topic of the message. Only required for channel messages\n(`\"type\": \"stream\"` or `\"type\": \"channel\"`), ignored otherwise.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", + "type": "string", + "example": "Castle" + }, + "scheduled_delivery_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message will be sent,\nin UTC seconds.\n", + "example": 3165826990 + }, + "read_by_sender": { + "type": "boolean", + "description": "Whether the message should be initially marked read by its\nsender. If unspecified, the server uses a heuristic based\non the client name and the recipient.\n\n**Changes**: New in Zulip 8.0 (feature level 236).\n", + "example": true + } + }, + "required": [ + "type", + "to", + "content", + "scheduled_delivery_timestamp" + ] + }, + "encoding": { + "to": { + "contentType": "application/json" + }, + "scheduled_delivery_timestamp": { + "contentType": "application/json" + }, + "read_by_sender": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "scheduled_message_id": { + "type": "integer", + "description": "The unique ID of the scheduled message.\n\nThis is different from the unique ID that the message will have\nafter it is sent.\n" + } + }, + "example": { + "msg": "", + "scheduled_message_id": 42, + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/NonExistingChannelIdError" + }, + { + "description": "A typical failed JSON response for when a channel message is scheduled\nto be sent to a channel that does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid user ID 10", + "result": "error" + }, + "description": "A typical failed JSON response for when a direct message is scheduled\nto be sent to a user that does not exist:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/scheduled_messages/{scheduled_message_id}": { + "patch": { + "operationId": "update-scheduled-message", + "tags": ["scheduled_messages"], + "summary": "Edit a scheduled message", + "description": "Edit an existing [scheduled message](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 184).\n", + "parameters": [ + { + "name": "scheduled_message_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the scheduled message to update.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", + "required": true, + "example": 2 + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of scheduled message to be sent. `\"direct\"` for a direct\nmessage and `\"stream\"` or `\"channel\"` for a channel message.\n\nWhen updating the type of the scheduled message, the `to` parameter\nis required. And, if updating the type of the scheduled message to\n`\"stream\"`/`\"channel\"`, then the `topic` parameter is also required.\n\nNote that, while `\"private\"` is supported for scheduling direct\nmessages, clients are encouraged to use to the modern convention of\n`\"direct\"` to indicate this message type, because support for\n`\"private\"` may eventually be removed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate the type of a channel\nmessage.\n", + "type": "string", + "enum": ["direct", "channel", "stream", "private"], + "example": "stream" + }, + "to": { + "description": "The scheduled message's tentative target audience.\n\nFor channel messages, the integer ID of the channel.\nFor direct messages, a list containing integer user IDs.\n\nRequired when updating the `type` of the scheduled message.\n", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "integer" + }, + "minLength": 1 + } + ], + "example": 11 + }, + "content": { + "description": "The updated content of the scheduled message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n", + "type": "string", + "example": "Hello" + }, + "topic": { + "description": "The updated topic of the scheduled message.\n\nRequired when updating the `type` of the scheduled message to\n`\"stream\"` or `\"channel\"`. Ignored when the existing or updated\n`type` of the scheduled message is `\"direct\"` (or `\"private\"`).\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", + "type": "string", + "example": "Castle" + }, + "scheduled_delivery_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message will be sent,\nin UTC seconds.\n\nRequired when updating a scheduled message that the server\nhas already tried and failed to send. This state is indicated\nwith `\"failed\": true` in `scheduled_messages` objects; see\nresponse description at\n[`GET /scheduled_messages`](/api/get-scheduled-messages#response).\n", + "example": 3165826990 + } + } + }, + "encoding": { + "to": { + "contentType": "application/json" + }, + "scheduled_delivery_timestamp": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {} + }, + "example": { + "result": "success", + "msg": "" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/NonExistingChannelIdError" + }, + { + "description": "A typical failed JSON response for when a channel message is scheduled\nto be sent to a channel that does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid user ID 10", + "result": "error" + }, + "description": "A typical failed JSON response for when a direct message is scheduled\nto be sent to a user that does not exist:\n" + } + ] + } + ] + } + } + } + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no scheduled message exists\nwith the provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Scheduled message does not exist" + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "delete-scheduled-message", + "tags": ["scheduled_messages"], + "summary": "Delete a scheduled message", + "description": "Delete, and therefore cancel sending, a previously [scheduled\nmessage](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n", + "parameters": [ + { + "name": "scheduled_message_id", + "in": "path", + "schema": { + "type": "integer" + }, + "description": "The ID of the scheduled message to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", + "required": true, + "example": 1 + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when no scheduled message exists\nwith the provided ID:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Scheduled message does not exist" + } + } + ] + } + } + } + } + } + } + }, + "/default_streams": { + "post": { + "operationId": "add-default-stream", + "tags": ["channels"], + "summary": "Add a default channel", + "x-requires-administrator": true, + "description": "Add a channel to the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the target channel.\n", + "type": "integer", + "example": 10 + } + }, + "required": ["stream_id"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "A typical failed JSON response for when an invalid channel ID is passed:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Private channels cannot be made default.", + "result": "error" + }, + "description": "A typical failed JSON response for when a user tries to add a private channel\nto the default channels set:\n" + } + ] + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "remove-default-stream", + "summary": "Remove a default channel", + "tags": ["channels"], + "description": "Remove a channel from the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", + "x-requires-administrator": true, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the target channel.\n", + "type": "integer", + "example": 10 + } + }, + "required": ["stream_id"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "A typical failed JSON response for when an invalid channel ID is passed:\n" + } + ] + } + } + } + } + } + } + }, + "/messages": { + "get": { + "operationId": "get-messages", + "summary": "Get messages", + "tags": ["messages"], + "description": "This endpoint is the primary way to fetch a messages. It is used by all official\nZulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as\nmany bots, API clients, backup scripts, etc.\n\nMost queries will specify a [narrow filter](/api/get-messages#parameter-narrow),\nto fetch the messages matching any supported [search\nquery](/help/search-for-messages). If not specified, it will return messages\ncorresponding to the user's [combined feed](/help/combined-feed). There are two\nways to specify which messages matching the narrow filter to fetch:\n\n- A range of messages, described by an `anchor` message ID (or a string-format\n specification of how the server should computer an anchor to use) and a maximum\n number of messages in each direction from that anchor.\n\n- A rarely used variant (`message_ids`) where the client specifies the message IDs\n to fetch.\n\nThe server returns the matching messages, sorted by message ID, as well as some\nmetadata that makes it easy for a client to determine whether there are more\nmessages matching the query that were not returned due to the `num_before` and\n`num_after` limits.\n\nNote that a user's message history does not contain messages sent to\nchannels before they [subscribe](/api/subscribe), and newly created\nbot users are not usually subscribed to any channels.\n\nWe recommend requesting at most 1000 messages in a batch, to avoid generating very\nlarge HTTP responses. A maximum of 5000 messages can be obtained per request;\nattempting to exceed this will result in an error.\n\n**Changes**: The `message_ids` option is new in Zulip 10.0 (feature level 300).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": [ + "client_gravatar", + "apply_markdown", + "use_first_unread_anchor", + "include_anchor", + "message_ids" + ] + } + } + ] + }, + "parameters": [ + { + "name": "anchor", + "in": "query", + "description": "Integer message ID to anchor fetching of new messages. Supports special\nstring values for when the client wants the server to compute the anchor\nto use:\n\n- `newest`: The most recent message.\n- `oldest`: The oldest message.\n- `first_unread`: The oldest unread message matching the\n query, if any; otherwise, the most recent message.\n\n**Changes**: String values are new in Zulip 3.0 (feature level 1). The\n`first_unread` functionality was supported in Zulip 2.1.x\nand older by not sending `anchor` and using `use_first_unread_anchor`.\n\nIn Zulip 2.1.x and older, `oldest` can be emulated with\n`\"anchor\": 0`, and `newest` with `\"anchor\": 10000000000000000`\n(that specific large value works around a bug in Zulip\n2.1.x and older in the `found_newest` return value).\n", + "schema": { + "$ref": "#/components/schemas/Anchor" + }, + "example": "43" + }, + { + "name": "include_anchor", + "in": "query", + "description": "Whether a message with the specified ID matching the narrow\nshould be included.\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + { + "name": "num_before", + "in": "query", + "description": "The number of messages with IDs less than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n", + "schema": { + "type": "integer", + "minimum": 0 + }, + "example": 4, + "required": false + }, + { + "name": "num_after", + "in": "query", + "description": "The number of messages with IDs greater than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n", + "schema": { + "type": "integer", + "minimum": 0 + }, + "example": 8, + "required": false + }, + { + "name": "narrow", + "in": "query", + "description": "The narrow where you want to fetch the messages from. See how to\n[construct a narrow](/api/construct-narrow).\n\nNote that many narrows, including all that lack a `channel`, `channels`,\n`stream`, or `streams` operator, search the user's personal message\nhistory. See [searching shared\nhistory](/help/search-for-messages#search-shared-history)\nfor details.\n\nFor example, if you would like to fetch messages from all public channels instead\nof only the user's message history, then a specific narrow for\nmessages sent to all public channels can be used:\n`{\"operator\": \"channels\", \"operand\": \"public\"}`.\n\nNewly created bot users are not usually subscribed to any\nchannels, so bots using this API should either be\nsubscribed to appropriate channels or use a shared history\nsearch narrow with this endpoint.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "required": ["operator", "operand"], + "additionalProperties": false, + "properties": { + "operator": { + "type": "string" + }, + "operand": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "integer" + } + } + ] + }, + "negated": { + "type": "boolean" + } + } + }, + { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 2, + "maxItems": 2 + } + ] + }, + "default": [] + }, + "example": [ + { + "operand": "Denmark", + "operator": "channel" + } + ] + } + } + }, + { + "$ref": "#/components/parameters/ClientGravatar" + }, + { + "name": "apply_markdown", + "in": "query", + "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\nMarkdown-format text that user entered.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + { + "name": "use_first_unread_anchor", + "in": "query", + "deprecated": true, + "description": "Legacy way to specify `\"anchor\": \"first_unread\"` in Zulip 2.1.x and older.\n\nWhether to use the (computed by the server) first unread message\nmatching the narrow as the `anchor`. Mutually exclusive with `anchor`.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by\n`\"anchor\": \"first_unread\"`.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "message_ids", + "in": "query", + "description": "A list of message IDs to fetch. The server will return messages corresponding to the\nsubset of the requested message IDs that exist and the current user has access to,\npotentially filtered by the narrow (if that parameter is provided).\n\nIt is an error to pass this parameter as well as any of the parameters involved in\nspecifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`,\n`num_before`, and `num_after`.\n\n**Changes**: New in Zulip 10.0 (feature level 300). Previously, there was\nno way to request a specific set of messages IDs.\n", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "integer" + } + }, + "example": [1, 2, 3] + } + } + }, + { + "name": "allow_empty_topic_name", + "in": "query", + "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": ["result", "msg", "messages"], + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "anchor": { + "type": "integer", + "description": "The same `anchor` specified in the request (or the computed one, if\n`use_first_unread_anchor` is `true`).\n\nOnly present if `message_ids` is not provided.\n" + }, + "found_newest": { + "type": "boolean", + "description": "Whether the server promises that the `messages` list includes the very\nnewest messages matching the narrow (used by clients that paginate their\nrequests to decide whether there may be more messages to fetch).\n" + }, + "found_oldest": { + "type": "boolean", + "description": "Whether the server promises that the `messages` list includes the very\noldest messages matching the narrow (used by clients that paginate their\nrequests to decide whether there may be more messages to fetch).\n" + }, + "found_anchor": { + "type": "boolean", + "description": "Whether the anchor message is included in the\nresponse. If the message with the ID specified\nin the request does not exist, did not match\nthe narrow, or was excluded via\n`\"include_anchor\": false`, this will be false.\n" + }, + "history_limited": { + "type": "boolean", + "description": "Whether the message history was limited due to\nplan restrictions. This flag is set to `true`\nonly when the oldest messages(`found_oldest`)\nmatching the narrow is fetched.\n" + }, + "messages": { + "type": "array", + "description": "An array of `message` objects.\n\n**Changes**: In Zulip 3.1 (feature level 26), the\n`sender_short_name` field was removed from message\nobjects.\n", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/MessagesBase" + }, + { + "additionalProperties": false, + "properties": { + "avatar_url": { + "nullable": true + }, + "client": {}, + "content": {}, + "content_type": {}, + "display_recipient": {}, + "edit_history": {}, + "id": {}, + "is_me_message": {}, + "last_edit_timestamp": {}, + "last_moved_timestamp": {}, + "reactions": {}, + "recipient_id": {}, + "sender_email": {}, + "sender_full_name": {}, + "sender_id": {}, + "sender_realm_str": {}, + "stream_id": {}, + "subject": {}, + "submessages": {}, + "timestamp": {}, + "topic_links": {}, + "type": {}, + "flags": { + "type": "array", + "description": "The user's [message flags][message-flags] for the message.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", + "items": { + "type": "string" + } + }, + "match_content": { + "type": "string", + "description": "Only present if keyword search was included among the narrow parameters.\n\nHTML content of a queried message that matches the narrow, with\n`` elements wrapping the matches for the\nsearch keywords.\n" + }, + "match_subject": { + "type": "string", + "description": "Only present if keyword search was included among the narrow parameters.\n\nHTML-escaped topic of a queried message that matches the narrow, with\n`` elements wrapping the matches for the\nsearch keywords.\n" + } + } + } + ] + } + } + }, + "example": { + "anchor": 21, + "found_newest": true, + "found_anchor": true, + "result": "success", + "msg": "", + "messages": [ + { + "subject": "", + "sender_realm_str": "zulip", + "type": "private", + "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", + "flags": ["read"], + "id": 16, + "display_recipient": [ + { + "id": 4, + "is_mirror_dummy": false, + "email": "hamlet@zulip.com", + "full_name": "King Hamlet" + }, + { + "id": 5, + "is_mirror_dummy": false, + "email": "iago@zulip.com", + "full_name": "Iago" + }, + { + "id": 8, + "is_mirror_dummy": false, + "email": "prospero@zulip.com", + "full_name": "Prospero from The Tempest" + } + ], + "content_type": "text/html", + "is_me_message": false, + "timestamp": 1527921326, + "sender_id": 4, + "sender_full_name": "King Hamlet", + "recipient_id": 27, + "topic_links": [], + "client": "ZulipDataImport", + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "submessages": [], + "sender_email": "hamlet@zulip.com", + "reactions": [] + }, + { + "subject": "Verona3", + "stream_id": 5, + "sender_realm_str": "zulip", + "type": "stream", + "content": "

Wait, is this from the frontend js code or backend python code

", + "flags": ["read"], + "id": 21, + "display_recipient": "Verona", + "content_type": "text/html", + "is_me_message": false, + "timestamp": 1527939746, + "sender_id": 4, + "sender_full_name": "King Hamlet", + "recipient_id": 20, + "topic_links": [], + "client": "ZulipDataImport", + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "submessages": [], + "sender_email": "hamlet@zulip.com", + "reactions": [] + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "send-message", + "summary": "Send a message", + "tags": ["messages"], + "description": "Send a [channel message](/help/introduction-to-topics) or a\n[direct message](/help/direct-messages).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of message to be sent.\n\n`\"direct\"` for a direct message and `\"stream\"` or `\"channel\"` for a\nchannel message.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to request a channel message.\n\nIn Zulip 7.0 (feature level 174), `\"direct\"` was added as\nthe preferred way to request a direct message, deprecating the original\n`\"private\"`. While `\"private\"` is still supported for requesting direct\nmessages, clients are encouraged to use to the modern convention with\nservers that support it, because support for `\"private\"` will eventually\nbe removed.\n", + "type": "string", + "enum": ["direct", "channel", "stream", "private"], + "example": "direct" + }, + "to": { + "description": "For channel messages, either the name or integer ID of the channel. For\ndirect messages, either a list containing integer user IDs or a list\ncontaining string Zulip API email addresses.\n\n**Changes**: Support for using user/channel IDs was added in Zulip 2.0.0.\n", + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "array", + "items": { + "type": "integer" + }, + "minLength": 1 + } + ], + "example": [9, 10] + }, + "content": { + "$ref": "#/components/schemas/RequiredContent" + }, + "topic": { + "description": "The topic of the message. Only required for channel messages\n(`\"type\": \"stream\"` or `\"type\": \"channel\"`), ignored otherwise.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 2.0.0. Previous Zulip releases encoded\nthis as `subject`, which is currently a deprecated alias.\n", + "type": "string", + "example": "Castle" + }, + "queue_id": { + "type": "string", + "description": "For clients supporting\n[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),\nthe [event queue](/api/register-queue)\nID for the client. If passed, `local_id` is required. If the message is\nsuccessfully sent, the server will include `local_id` in the `message` event\nthat the client with this `queue_id` will receive notifying it of the new message\nvia [`GET /events`](/api/get-events). This lets the client know unambiguously\nthat it should replace the locally echoed message, rather than adding this new\nmessage (which would be correct if the user had sent the new message from another\ndevice).\n", + "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8" + }, + "local_id": { + "type": "string", + "description": "For clients supporting local echo, a unique string-format identifier\nchosen freely by the client; the server will pass it back to the client without\ninspecting it, as described in the `queue_id` description.\n", + "example": "100.01" + }, + "read_by_sender": { + "type": "boolean", + "description": "Whether the message should be initially marked read by its\nsender. If unspecified, the server uses a heuristic based\non the client name.\n\n**Changes**: New in Zulip 8.0 (feature level 236).\n", + "example": true + } + }, + "required": ["type", "to", "content"] + }, + "encoding": { + "to": { + "contentType": "application/json" + }, + "read_by_sender": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": ["id"], + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The unique ID assigned to the sent message.\n" + }, + "automatic_new_visibility_policy": { + "type": "integer", + "enum": [2, 3], + "description": "If the message's sender had configured their [visibility policy settings](/help/mute-a-topic)\nto potentially automatically follow or unmute topics when sending messages,\nand one of these policies did in fact change the user's visibility policy\nfor the topic where this message was sent, the new value for that user's\nvisibility policy for the recipient topic.\n\nOnly present if the sender's visibility was in fact changed.\n\nThe value can be either [unmuted or followed](/api/update-user-topic#parameter-visibility_policy).\n\nClients will also be notified about the change in policy via a\n`user_topic` event as usual. This field is intended to be used by clients\nto explicitly inform the user when a topic's visibility policy was changed\nautomatically due to sending a message.\n\nFor example, the Zulip web application uses this field to decide whether\nto display a warning or notice suggesting to unmute the topic after\nsending a message to a muted channel. Such a notice would be confusing in\nthe event that the act of sending the message had already resulted in the\nuser automatically unmuting or following the topic in question.\n\n**Changes**: New in Zulip 8.0 (feature level 218).\n" + } + }, + "example": { + "msg": "", + "id": 42, + "automatic_new_visibility_policy": 2, + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/NonExistingChannelNameError" + }, + { + "description": "A typical failed JSON response for when a channel message is sent to a channel\nthat does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid email 'eeshan@zulip.com'", + "result": "error" + }, + "description": "A typical failed JSON response for when a direct message is sent to a user\nthat does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "You do not have permission to use channel wildcard mentions in this channel.", + "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED" + }, + "description": "An example JSON error response for when the message was rejected because\nthe message contains a stream wildcard mention, but the user doesn't have\npermission to use such a mention in this channel as the user is not present\nin `can_mention_many_users_group` and the channel contains a large number\nof subscribers.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "You do not have permission to use topic wildcard mentions in this topic.", + "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED" + }, + "description": "An example JSON error response for when the message was rejected because\nthe message contains a topic wildcard mention, but the user doesn't have\npermission to use such a mention in this topic as the user is not present\nin `can_mention_many_users_group` and the topic contains a large number\nof participants.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously,\n`wildcard_mention_policy` was not enforced for topic mentions.\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}/history": { + "get": { + "operationId": "get-message-history", + "summary": "Get a message's edit history", + "tags": ["messages"], + "description": "Fetch the message edit history of a previously edited message.\n\nNote that edit history may be disabled in some organizations; see the\n[Zulip help center documentation on editing messages][edit-settings].\n\n[edit-settings]: /help/view-a-messages-edit-history\n", + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + }, + { + "name": "allow_empty_topic_name", + "in": "query", + "description": "Whether the topic names i.e. `topic` and `prev_topic` fields in\nthe `message_history` objects returned can be empty string.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334).\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + } + ], + "x-response-description": "Please note that the original message's snapshot only contains the fields\n`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This\nsnapshot will be the only one present if the message has never been edited.\n\nAlso note that each snapshot object will only contain additional data for the\nmodified fields for that particular edit (e.g. if only the topic or channel\nwas edited, `prev_content`, `prev_rendered_content`, and\n`content_html_diff` will not appear).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "message_history": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "topic": { + "type": "string", + "description": "The topic of the message immediately\nafter this edit event.\n" + }, + "prev_topic": { + "type": "string", + "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately\nprior to this edit event.\n" + }, + "stream": { + "type": "integer", + "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message\nimmediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" + }, + "prev_stream": { + "type": "integer", + "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message immediately\nprior to this edit event.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n" + }, + "content": { + "type": "string", + "description": "The raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) content of the message\nimmediately after this edit event.\n" + }, + "rendered_content": { + "type": "string", + "description": "The rendered HTML representation of `content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "prev_content": { + "type": "string", + "description": "Only present if message's content was edited.\n\nThe raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) content of the message immediately\nprior to this edit event.\n" + }, + "prev_rendered_content": { + "type": "string", + "description": "Only present if message's content was edited.\n\nThe rendered HTML representation of `prev_content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "user_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user that made the edit.\n\nWill be `null` only for edit history\nevents predating March 2017.\n\nClients can display edit history events where this\nis `null` as modified by either the sender (for content\nedits) or an unknown user (for topic edits).\n" + }, + "content_html_diff": { + "type": "string", + "description": "Only present if message's content was edited.\n\nAn HTML diff between this version of the message\nand the previous one.\n" + }, + "timestamp": { + "type": "integer", + "description": "The UNIX timestamp for this edit.\n" + } + } + }, + "description": "A chronologically sorted, oldest to newest, array\nof `snapshot` objects, each one with the values of\nthe message after the edit.\n" + } + }, + "example": { + "message_history": [ + { + "content": "Hello!", + "topic": "party at my houz", + "rendered_content": "

Hello!

", + "timestamp": 1530129122, + "user_id": 5 + }, + { + "topic": "party at my house", + "content": "Howdy!", + "prev_content": "Hello!", + "rendered_content": "

Howdy!

", + "user_id": 5, + "prev_rendered_content": "

Hello!

", + "content_html_diff": "

Howdy!

Hello!

", + "prev_topic": "party at my houz", + "timestamp": 1530129134 + } + ], + "msg": "", + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidMessageError" + }, + { + "description": "An example JSON response for when the specified message does not exist:\n" + } + ] + } + } + } + } + } + } + }, + "/messages/flags": { + "post": { + "operationId": "update-message-flags", + "summary": "Update personal message flags", + "tags": ["messages"], + "description": "Add or remove personal message flags like `read` and `starred`\non a collection of message IDs.\n\nSee also the endpoint for [updating flags on a range of\nmessages within a narrow](/api/update-message-flags-for-narrow).\n", + "x-parameter-description": "## Available flags\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FlagPurpose
read\n Whether the user has read the message. Messages\n start out unread (except for messages the user\n themself sent using a non-API client) and can\n later be marked as read.\n
starredWhether the user has starred this message.
collapsedWhether the user has collapsed this message.
mentioned\n Whether the current user\n was mentioned\n by this message, either directly or via a user\n group. Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n a mention of the current user.\n
stream_wildcard_mentioned\n Whether this message contained a\n channel wildcard mention\n (like @**all**). Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n a channel wildcard mention.\n

\n Changes: New in Zulip 8.0 (feature level 224).\n
topic_wildcard_mentioned\n Whether this message contained a\n topic wildcard mention\n (@**topic**).\n Cannot be changed by the user directly, but can change if\n the message is edited to add/remove a topic wildcard mention.\n

\n Changes: New in Zulip 8.0 (feature level 224).\n
has_alert_word\n Whether the message contains any of the current user's\n configured alert words.\n Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n one of the current user's alert words.\n
historical\n Is true for messages that the user did not receive\n at the time they were sent but later was added to\n the user's history (e.g. because they starred or\n reacted to a message sent to a public channel\n before they subscribed to that channel). Cannot be\n changed by the user directly.\n
wildcard_mentioned\n Whether this message contained either a\n channel wildcard mention\n (like @**all**) or a\n topic wildcard mention\n (@**topic**). Cannot be changed by the user directly, but can change if\n the message is edited to add/remove a channel and/or topic wildcard\n mention.\n

\n Changes: Deprecated in Zulip 8.0 (feature level 224), in favor of\n the stream_wildcard_mentioned and\n topic_wildcard_mentioned flags. The\n wildcard_mentioned flag exists for backwards compatibility\n with older clients and equals\n stream_wildcard_mentioned || topic_wildcard_mentioned.\n Clients supporting older server versions should treat this field as a\n previous name for the stream_wildcard_mentioned flag as\n topic wildcard mentions were not available prior to this feature level.\n
\n
\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "messages": { + "description": "An array containing the IDs of the target messages.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [4, 8, 15] + }, + "op": { + "description": "Whether to `add` the flag or `remove` it.\n", + "type": "string", + "enum": ["add", "remove"], + "example": "add" + }, + "flag": { + "description": "The flag that should be added/removed.\n", + "type": "string", + "example": "read" + } + }, + "required": ["messages", "op", "flag"] + }, + "encoding": { + "messages": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "messages": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "An array with the IDs of the modified messages.\n" + }, + "ignored_because_not_subscribed_channels": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Only present if the flag is `read` and the operation is `remove`.\n\nZulip has an invariant that all unread messages must be in channels\nthe user is subscribed to. This field will contain a list of the\nchannels whose messages were skipped to mark as unread because the\nuser is not subscribed to them.\n\n**Changes**: New in Zulip 10.0 (feature level 355).\n" + } + }, + "example": { + "msg": "", + "messages": [4, 18, 15], + "ignored_because_not_subscribed_channels": [12, 13, 9], + "result": "success" + } + } + ] + } + } + } + } + } + } + }, + "/messages/flags/narrow": { + "post": { + "operationId": "update-message-flags-for-narrow", + "summary": "Update personal message flags for narrow", + "tags": ["messages"], + "description": "Add or remove personal message flags like `read` and `starred`\non a range of messages within a narrow.\n\nSee also [the endpoint for updating flags on specific message\nIDs](/api/update-message-flags).\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["include_anchor"] + } + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "anchor": { + "allOf": [ + { + "$ref": "#/components/schemas/Anchor" + }, + { + "description": "Integer message ID to anchor updating of flags. Supports special\nstring values for when the client wants the server to compute the anchor\nto use:\n\n- `newest`: The most recent message.\n- `oldest`: The oldest message.\n- `first_unread`: The oldest unread message matching the\n query, if any; otherwise, the most recent message.\n", + "example": "43" + } + ] + }, + "include_anchor": { + "description": "Whether a message with the specified ID matching the narrow\nshould be included in the update range.\n", + "type": "boolean", + "default": true, + "example": false + }, + "num_before": { + "description": "Limit the number of messages preceding the anchor in the\nupdate range. The server may decrease this to bound\ntransaction sizes.\n", + "type": "integer", + "minimum": 0, + "example": 4 + }, + "num_after": { + "description": "Limit the number of messages following the anchor in the\nupdate range. The server may decrease this to bound\ntransaction sizes.\n", + "type": "integer", + "minimum": 0, + "example": 8 + }, + "narrow": { + "description": "The narrow you want update flags within. See how to\n[construct a narrow](/api/construct-narrow).\n\nNote that, when adding the `read` flag to messages, clients should\nconsider including a narrow with the `is:unread` filter as an\noptimization. Including that filter takes advantage of the fact that\nthe server has a database index for unread messages.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "required": ["operator", "operand"], + "additionalProperties": false, + "properties": { + "operator": { + "type": "string" + }, + "operand": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "integer" + } + } + ] + }, + "negated": { + "type": "boolean" + } + } + }, + { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 2, + "maxItems": 2 + } + ] + }, + "default": [], + "example": [ + { + "operand": "Denmark", + "operator": "channel" + } + ] + }, + "op": { + "description": "Whether to `add` the flag or `remove` it.\n", + "type": "string", + "enum": ["add", "remove"], + "example": "add" + }, + "flag": { + "description": "The flag that should be added/removed. See [available\nflags](/api/update-message-flags#available-flags).\n", + "type": "string", + "example": "read" + } + }, + "required": [ + "anchor", + "num_before", + "num_after", + "narrow", + "op", + "flag" + ] + }, + "encoding": { + "include_anchor": { + "contentType": "application/json" + }, + "num_before": { + "contentType": "application/json" + }, + "num_after": { + "contentType": "application/json" + }, + "narrow": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": [ + "processed_count", + "updated_count", + "first_processed_id", + "last_processed_id", + "found_oldest", + "found_newest" + ], + "properties": { + "result": {}, + "msg": {}, + "processed_count": { + "type": "integer", + "description": "The number of messages that were within the\nupdate range (at most `num_before + 1 +\nnum_after`).\n" + }, + "updated_count": { + "type": "integer", + "description": "The number of messages where the flag's\nvalue was changed (at most\n`processed_count`).\n" + }, + "first_processed_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the oldest message within the\nupdate range, or `null` if the range was\nempty.\n" + }, + "last_processed_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the newest message within the\nupdate range, or `null` if the range was\nempty.\n" + }, + "found_oldest": { + "type": "boolean", + "description": "Whether the update range reached backward\nfar enough to include very oldest message\nmatching the narrow (used by clients doing a\nbulk update to decide whether to issue\nanother request anchored at\n`first_processed_id`).\n" + }, + "found_newest": { + "type": "boolean", + "description": "Whether the update range reached forward far\nenough to include very oldest message\nmatching the narrow (used by clients doing a\nbulk update to decide whether to issue\nanother request anchored at\n`last_processed_id`).\n" + }, + "ignored_because_not_subscribed_channels": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Only present if the flag is `read` and the operation is `remove`.\n\nZulip has an invariant that all unread messages must be in channels\nthe user is subscribed to. This field will contain a list of the\nchannels whose messages were skipped to mark as unread because the\nuser is not subscribed to them.\n\n**Changes**: New in Zulip 10.0 (feature level 355).\n" + } + }, + "example": { + "result": "success", + "msg": "", + "processed_count": 11, + "updated_count": 8, + "first_processed_id": 35, + "last_processed_id": 55, + "found_oldest": false, + "found_newest": true, + "ignored_because_not_subscribed_channels": [12, 13, 9] + } + } + ] + } + } + } + } + } + } + }, + "/messages/render": { + "post": { + "operationId": "render-message", + "summary": "Render a message", + "tags": ["messages"], + "description": "Render a message to HTML.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "content": { + "$ref": "#/components/schemas/RequiredContent" + } + }, + "required": ["content"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "rendered": { + "type": "string", + "description": "The rendered HTML.\n" + } + }, + "example": { + "msg": "", + "rendered": "

foo

", + "result": "success" + } + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}/reactions": { + "post": { + "operationId": "add-reaction", + "summary": "Add an emoji reaction", + "tags": ["messages"], + "description": "Add an [emoji reaction](/help/emoji-reactions) to a message.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["emoji_code", "reaction_type"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "emoji_name": { + "description": "The target emoji's human-readable name.\n\nTo find an emoji's name, hover over a message to reveal\nthree icons on the right, then click the smiley face icon.\nImages of available reaction emojis appear. Hover over the\nemoji you want, and note that emoji's text name.\n", + "type": "string", + "example": "octopus" + }, + "emoji_code": { + "$ref": "#/components/schemas/EmojiCode" + }, + "reaction_type": { + "$ref": "#/components/schemas/ReactionType" + } + }, + "required": ["emoji_name"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid emoji code", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response for when the emoji code is invalid:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Reaction already exists.", + "code": "REACTION_ALREADY_EXISTS" + }, + "description": "An example JSON error response for when the reaction already exists.\n\n**Changes**: New in Zulip 8.0 (feature level 193). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" + } + ] + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "remove-reaction", + "summary": "Remove an emoji reaction", + "tags": ["messages"], + "description": "Remove an [emoji reaction](/help/emoji-reactions) from a message.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["emoji_code", "reaction_type"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "emoji_name": { + "description": "The target emoji's human-readable name.\n\nTo find an emoji's name, hover over a message to reveal\nthree icons on the right, then click the smiley face icon.\nImages of available reaction emojis appear. Hover over the\nemoji you want, and note that emoji's text name.\n", + "type": "string", + "example": "octopus" + }, + "emoji_code": { + "$ref": "#/components/schemas/EmojiCode" + }, + "reaction_type": { + "$ref": "#/components/schemas/ReactionType" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid emoji code", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response for when the emoji code is invalid:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Reaction doesn't exist.", + "code": "REACTION_DOES_NOT_EXIST" + }, + "description": "An example JSON error response for when the reaction does not exist.\n\n**Changes**: New in Zulip 8.0 (feature level 193). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}/read_receipts": { + "get": { + "operationId": "get-read-receipts", + "summary": "Get a message's read receipts", + "tags": ["messages"], + "description": "Returns a list containing the IDs for all users who have\nmarked the message as read (and whose privacy settings allow\nsharing that information).\n\nThe list of users IDs will include any bots who have marked\nthe message as read via the API (providing a way for bots to\nindicate whether they have processed a message successfully in\na way that can be easily inspected in a Zulip client). Bots\nfor which this behavior is not desired may disable the\n`send_read_receipts` setting via the API.\n\nIt will never contain the message's sender.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n", + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "user_ids": { + "type": "array", + "description": "An array of IDs of users who have marked the target message as\nread and whose read status is available to the current user.\n\nThe IDs of users who have disabled sending read receipts\n(`\"send_read_receipts\": false`) will never appear in the response,\nnor will the message's sender. Additionally, the IDs of any users\nwho have been muted by the current user or who have muted the\ncurrent user will not be included in the response.\n\nThe current user's ID will appear if they have marked the target\nmessage as read.\n\n**Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of\nusers who have been muted by or have muted the current user were\nincluded in the response.\n", + "items": { + "type": "integer" + } + } + }, + "example": { + "msg": "", + "result": "success", + "user_ids": [3, 7, 9] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidMessageError" + }, + { + "description": "A typical JSON response when attempting to access read receipts for\na message ID that either does not exist or is not accessible to the\ncurrent user:\n" + } + ] + } + } + } + } + } + } + }, + "/messages/matches_narrow": { + "get": { + "operationId": "check-messages-match-narrow", + "summary": "Check if messages match a narrow", + "tags": ["messages"], + "description": "Check whether a set of messages match a [narrow](/api/construct-narrow).\n\nFor many common narrows (e.g. a topic), clients can write an efficient\nclient-side check to determine whether a newly arrived message belongs\nin the view.\n\nThis endpoint is designed to allow clients to handle more complex narrows\nfor which the client does not (or in the case of full-text search, cannot)\nimplement this check.\n\nThe format of the `match_subject` and `match_content` objects is designed\nto match those returned by the [`GET /messages`](/api/get-messages#response)\nendpoint, so that a client can splice these fields into a `message` object\nreceived from [`GET /events`](/api/get-events#message) and end up with an\nextended message object identical to how a [`GET /messages`](/api/get-messages)\nrequest for the current narrow would have returned the message.\n", + "parameters": [ + { + "name": "msg_ids", + "in": "query", + "description": "List of IDs for the messages to check.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "integer" + } + }, + "example": [31, 32] + } + }, + "required": true + }, + { + "name": "narrow", + "in": "query", + "description": "A structure defining the narrow to check against. See how to\n[construct a narrow](/api/construct-narrow).\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object" + } + }, + "example": [ + { + "operator": "has", + "operand": "link" + } + ] + } + }, + "required": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "messages": { + "type": "object", + "description": "A dictionary with a key for each queried message that matches the narrow,\nwith message IDs as keys and search rendering data as values.\n", + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "properties": { + "match_content": { + "type": "string", + "description": "HTML content of a queried message that matches the narrow. If the\nnarrow is a search narrow, `` elements\nwill be included, wrapping the matches for the search keywords.\n" + }, + "match_subject": { + "type": "string", + "description": "HTML-escaped topic of a queried message that matches the narrow. If the\nnarrow is a search narrow, `` elements\nwill be included wrapping the matches for the search keywords.\n" + } + }, + "description": "`message_id`: The ID of the message that matches the narrow. No record will be returned\nfor queried messages that do not match the narrow.\n" + } + } + }, + "example": { + "result": "success", + "msg": "", + "messages": { + "31": { + "match_content": "

http://foo.com

", + "match_subject": "test_topic" + } + } + } + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}": { + "get": { + "operationId": "get-message", + "summary": "Fetch a single message", + "tags": ["messages"], + "description": "Given a message ID, return the message object.\n\nAdditionally, a `raw_content` field is included. This field is\nuseful for clients that primarily work with HTML-rendered\nmessages but might need to occasionally fetch the message's\nraw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) (e.g. for [view\nsource](/help/view-the-markdown-source-of-a-message) or\nprefilling a message edit textarea).\n\n**Changes**: Before Zulip 5.0 (feature level 120), this\nendpoint only returned the `raw_content` field.\n", + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + }, + { + "name": "apply_markdown", + "in": "query", + "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\n[Zulip-flavored Markdown format](/help/format-your-message-using-markdown) text that user entered.\n\n**Changes**: New in Zulip 5.0 (feature level 120).\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + { + "name": "allow_empty_topic_name", + "in": "query", + "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "raw_content": { + "type": "string", + "deprecated": true, + "description": "The raw Markdown content of the message.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n\n**Deprecated** and to be removed once no longer required for\nlegacy clients. Modern clients should prefer passing\n`\"apply_markdown\": false` to request raw message content.\n" + }, + "message": { + "description": "An object containing details of the message.\n\n**Changes**: New in Zulip 5.0 (feature level 120).\n", + "allOf": [ + { + "$ref": "#/components/schemas/MessagesBase" + }, + { + "additionalProperties": false, + "properties": { + "avatar_url": { + "nullable": true + }, + "client": {}, + "content": {}, + "content_type": {}, + "display_recipient": {}, + "edit_history": {}, + "id": {}, + "is_me_message": {}, + "last_edit_timestamp": {}, + "last_moved_timestamp": {}, + "reactions": {}, + "recipient_id": {}, + "sender_email": {}, + "sender_full_name": {}, + "sender_id": {}, + "sender_realm_str": {}, + "stream_id": {}, + "subject": {}, + "submessages": {}, + "timestamp": {}, + "topic_links": {}, + "type": {}, + "flags": { + "type": "array", + "description": "The user's [message flags][message-flags] for the message.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", + "items": { + "type": "string" + } + } + } + } + ] + } + }, + "example": { + "raw_content": "**Don't** forget your towel!", + "result": "success", + "msg": "", + "message": { + "subject": "", + "sender_realm_str": "zulip", + "type": "private", + "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", + "flags": ["read"], + "id": 16, + "display_recipient": [ + { + "id": 4, + "is_mirror_dummy": false, + "email": "hamlet@zulip.com", + "full_name": "King Hamlet" + }, + { + "id": 5, + "is_mirror_dummy": false, + "email": "iago@zulip.com", + "full_name": "Iago" + }, + { + "id": 8, + "is_mirror_dummy": false, + "email": "prospero@zulip.com", + "full_name": "Prospero from The Tempest" + } + ], + "content_type": "text/html", + "is_me_message": false, + "timestamp": 1527921326, + "sender_id": 4, + "sender_full_name": "King Hamlet", + "recipient_id": 27, + "topic_links": [], + "client": "ZulipDataImport", + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "submessages": [], + "sender_email": "hamlet@zulip.com", + "reactions": [] + } + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidMessageError" + }, + { + "description": "An example JSON response for when the specified message does not exist or it\nis not visible to the user making the query (e.g. it was a direct message\nbetween two other users):\n" + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "update-message", + "summary": "Edit a message", + "tags": ["messages"], + "description": "Update the content, topic, or channel of the message with the specified\nID.\n\nYou can [resolve topics](/help/resolve-a-topic) by editing the topic to\n`✔ {original_topic}` with the `propagate_mode` parameter set to\n`\"change_all\"`.\n\nSee [configuring message editing][config-message-editing] for detailed\ndocumentation on when users are allowed to edit message content, and\n[restricting moving messages][restrict-move-messages] for detailed\ndocumentation on when users are allowed to change a message's topic\nand/or channel.\n\nThe relevant realm settings in the API that are related to the above\nlinked documentation on when users are allowed to update messages are:\n\n- `allow_message_editing`\n- `can_resolve_topics_group`\n- `can_move_messages_between_channels_group`\n- `can_move_messages_between_topics_group`\n- `message_content_edit_limit_seconds`\n- `move_messages_within_stream_limit_seconds`\n- `move_messages_between_streams_limit_seconds`\n\nMore details about these realm settings can be found in the\n[`POST /register`](/api/register-queue) response or in the documentation\nof the [`realm op: update_dict`](/api/get-events#realm-update_dict)\nevent in [`GET /events`](/api/get-events).\n\n**Changes**: Prior to Zulip 10.0 (feature level 367), the permission for\nresolving a topic was managed by `can_move_messages_between_topics_group`.\nAs of this feature level, users belonging to the `can_resolve_topics_group`\nwill have the permission to [resolve topics](/help/resolve-a-topic) in the organization.\n\nIn Zulip 10.0 (feature level 316), `edit_topic_policy`\nwas removed and replaced by `can_move_messages_between_topics_group`\nrealm setting.\n\n**Changes**: In Zulip 10.0 (feature level 310), `move_messages_between_streams_policy`\nwas removed and replaced by `can_move_messages_between_channels_group`\nrealm setting.\n\nPrior to Zulip 7.0 (feature level 172), anyone could add a\ntopic to channel messages without a topic, regardless of the organization's\n[topic editing permissions](/help/restrict-moving-messages). As of this\nfeature level, messages without topics have the same restrictions for\ntopic edits as messages with topics.\n\nBefore Zulip 7.0 (feature level 172), by using the `change_all` value for\nthe `propagate_mode` parameter, users could move messages after the\norganization's configured time limits for changing a message's topic or\nchannel had passed. As of this feature level, the server will [return an\nerror](/api/update-message#response) with `\"code\":\n\"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED\"` if users, other than organization\nadministrators or moderators, try to move messages after these time\nlimits have passed.\n\nBefore Zulip 7.0 (feature level 162), users who were not administrators or\nmoderators could only edit topics if the target message was sent within the\nlast 3 days. As of this feature level, that time limit is now controlled by\nthe realm setting `move_messages_within_stream_limit_seconds`. Also at this\nfeature level, a similar time limit for moving messages between channels was\nadded, controlled by the realm setting\n`move_messages_between_streams_limit_seconds`. Previously, all users who\nhad permission to move messages between channels did not have any time limit\nrestrictions when doing so.\n\nBefore Zulip 7.0 (feature level 159), editing channels and topics of messages\nwas forbidden if the realm setting for `allow_message_editing` was `false`,\nregardless of an organization's configuration for the realm settings\n`edit_topic_policy` or `move_messages_between_streams_policy`.\n\nBefore Zulip 7.0 (feature level 159), message senders were allowed to edit\nthe topic of their messages indefinitely.\n\nIn Zulip 5.0 (feature level 75), the `edit_topic_policy` realm setting\nwas added, replacing the `allow_community_topic_editing` boolean.\n\nIn Zulip 4.0 (feature level 56), the `move_messages_between_streams_policy`\nrealm setting was added.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n[restrict-move-messages]: /help/restrict-moving-messages\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["stream_id"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "topic": { + "description": "The topic to move the message(s) to, to request changing the topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length\n\nShould only be sent when changing the topic, and will throw an error\nif the target message is not a channel message.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\nYou can [resolve topics](/help/resolve-a-topic) by editing the topic to\n`✔ {original_topic}` with the `propagate_mode` parameter set to\n`\"change_all\"`. The empty string topic cannot be marked as resolved.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 2.0.0. Previous Zulip releases encoded this as `subject`,\nwhich is currently a deprecated alias.\n", + "type": "string", + "example": "Castle" + }, + "propagate_mode": { + "description": "Which message(s) should be edited:\n\n- `\"change_later\"`: The target message and all following messages.\n- `\"change_one\"`: Only the target message.\n- `\"change_all\"`: All messages in this topic.\n\nOnly the default value of `\"change_one\"` is valid when editing\nonly the content of a message.\n\nThis parameter determines both which messages get moved and also whether\nclients that are currently narrowed to the topic containing the message\nshould navigate or adjust their compose box recipient to point to the\npost-edit channel/topic.\n", + "type": "string", + "enum": ["change_one", "change_later", "change_all"], + "default": "change_one", + "example": "change_all" + }, + "send_notification_to_old_thread": { + "description": "Whether to send an automated message to the old topic to\nnotify users where the messages were moved to.\n\n**Changes**: Before Zulip 6.0 (feature level 152), this parameter\nhad a default of `true` and was ignored unless the channel was changed.\n\nNew in Zulip 3.0 (feature level 9).\n", + "type": "boolean", + "default": false, + "example": true + }, + "send_notification_to_new_thread": { + "description": "Whether to send an automated message to the new topic to\nnotify users where the messages came from.\n\nIf the move is just [resolving/unresolving a topic](/help/resolve-a-topic),\nthis parameter will not trigger an additional notification.\n\n**Changes**: Before Zulip 6.0 (feature level 152), this parameter\nwas ignored unless the channel was changed.\n\nNew in Zulip 3.0 (feature level 9).\n", + "type": "boolean", + "default": true, + "example": true + }, + "content": { + "$ref": "#/components/schemas/OptionalContent" + }, + "prev_content_sha256": { + "description": "An optional SHA-256 hash of the previous raw content of the message\nthat the client has at the time of the request.\n\nIf provided, the server will return an error if it does not match the\nSHA-256 hash of the message's content stored in the database.\n\nClients can use this feature to prevent races where multiple clients\nsave conflicting edits to a message.\n\n**Changes**: New in Zulip 11.0 (feature level 379).\n", + "type": "string", + "example": "6ae8a75555209fd6c44157c0aed8016e763ff435a19cf186f76863140143ff72" + }, + "stream_id": { + "description": "The channel ID to move the message(s) to, to request moving\nmessages to another channel.\n\nShould only be sent when changing the channel, and will throw an error\nif the target message is not a channel message.\n\nNote that a message's content and channel cannot be changed at the\nsame time, so sending both `content` and `stream_id` parameters will\nthrow an error.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", + "type": "integer", + "example": 43 + } + } + }, + "encoding": { + "send_notification_to_old_thread": { + "contentType": "application/json" + }, + "send_notification_to_new_thread": { + "contentType": "application/json" + }, + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "detached_uploads": { + "type": "array", + "description": "Details on all files uploaded by the acting user whose only references\nwere removed when editing this message. Clients should ask the acting user\nif they wish to delete the uploaded files returned in this response,\nwhich might otherwise remain visible only in message edit history.\n\nNote that [access to message edit history][edit-history-access]\nis configurable; this detail may be important in presenting the\nquestion clearly to users.\n\nNew in Zulip 10.0 (feature level 285).\n\n[edit-history-access]: /help/restrict-message-edit-history-access\n", + "items": { + "$ref": "#/components/schemas/Attachment" + } + } + }, + "example": { + "result": "success", + "msg": "", + "detached_uploads": [ + { + "id": 3, + "name": "1253601-1.jpg", + "path_id": "2/5d/BD5NRptFxPDKY3RUKwhhup8r/1253601-1.jpg", + "size": 1339060, + "create_time": 1687984706000, + "messages": [] + } + ] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "properties": { + "msg": { + "enum": [ + "Your organization has turned off message editing", + "You don't have permission to edit this message", + "The time limit for editing this message has past", + "Nothing to change", + "Topic can't be empty" + ] + } + }, + "example": { + "code": "BAD_REQUEST", + "msg": "You don't have permission to edit this message", + "result": "error" + }, + "description": "A typical JSON response for when one doesn't have the permission to\nedit a particular message:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED", + "first_message_id_allowed_to_move": 123, + "msg": "You only have permission to move the 2/5 most recent messages in this topic.", + "result": "error", + "total_messages_allowed_to_move": 2, + "total_messages_in_topic": 5 + }, + "description": "A special failed JSON response (`\"code\": \"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED\"`)\nfor when the user has permission to move\nthe target message, but asked to move all messages in a topic\n(`\"propagate_mode\": \"change_all\"`) and the user does not have permission\nto move the entire topic.\n\nThis happens when the topic contains some messages that are older than an\napplicable time limit for the requested topic move (see\n`move_messages_within_stream_limit_seconds` and/or\n`move_messages_between_streams_limit_seconds` in the\n[`POST /register`](/api/register-queue) response).\n\nThe error response contains data on which portion of this topic the user has\npermission to move. `first_message_id_allowed_to_move` is the oldest message\nID in this topic that the user has permission to move.\nThere are `total_messages_in_topic` in the topic, but the user only has\npermission to move the (most recent) `total_messages_allowed_to_move`\nmessages.\n\nClients should support this error code with\n`\"first_message_id_allowed_to_move\": null` for forward compatibility\nwith future server versions that may use this error code with other\npropagation modes where the user does not have permission to move any\nmessages, or where the server did not calculate the total message counts\nnoted above.\n\nClients can either only present the error to the user or, if\n`first_message_id_allowed_to_move` is not `null`, prompt the user to adjust\ntheir query with the above information.\n\nIf clients choose to present a prompt for this error code, they should\nrecommend the option of cancelling and (manually) asking a moderator to\nmove the entire topic, since that's often a better experience than\npartially moving a topic. This API supports a client that wishes to allow\nthe user to repeat the request with a `change_later` propagation mode and\na target message ID of `first_message_id_allowed_to_move`, if the user\ndesires to move only the portion of the topic that they can.\n\nNote that in a [private channel with protected history][private-channels],\nthe Zulip security model requires that the above calculations only include\nmessages the acting user has access to. So in the rare case of a user\nattempting to move a topic that started before the user joined a private\nchannel with protected history, this API endpoint might move only the portion\nof a topic that they have access to, without this error or any confirmation\ndialog.\n\n**Changes**: New in Zulip 7.0 (feature level 172).\n\n[private-channels]: /help/channel-permissions#private-channels\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "You do not have permission to use channel wildcard mentions in this channel.", + "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED" + }, + "description": "An example JSON error response for when the message was rejected because\nthe message contains a stream wildcard mention, but the user doesn't have\npermission to use such a mention in this channel as the user is not present\nin `can_mention_many_users_group` and the channel contains a large number\nof subscribers.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "You do not have permission to use topic wildcard mentions in this topic.", + "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED" + }, + "description": "An example JSON error response for when the message was rejected because\nthe message contains a topic wildcard mention, but the user doesn't have\npermission to use such a mention in this topic as the user is not present\nin `can_mention_many_users_group` and the topic contains a large number\nof participants.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously,\n`wildcard_mention_policy` was not enforced for topic mentions.\n" + } + ] + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "delete-message", + "summary": "Delete a message", + "tags": ["messages"], + "description": "Permanently delete a message.\n\nThis API corresponds to the\n[delete a message completely][delete-completely] feature documented in\nthe Zulip help center.\n\n[delete-completely]: /help/delete-a-message#delete-a-message-completely\n", + "x-requires-administrator": true, + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidMessageError" + }, + { + "description": "An example JSON response for when the specified message does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "An example JSON response for when the user making the query does not\nhave permission to delete the message:\n", + "example": { + "code": "BAD_REQUEST", + "msg": "You don't have permission to delete this message", + "result": "error" + } + } + ] + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}/report": { + "post": { + "operationId": "report-message", + "summary": "Report a message", + "tags": ["messages"], + "description": "Sends a notification to the organization's moderation request channel,\nif it is configured, that reports the targeted message for review and\nmoderation.\n\nClients should check the `moderation_request_channel` realm setting to\ndecide whether to show the option to report messages in the UI.\n\nIf the `report_type` parameter value is `\"other\"`, the `description`\nparameter is required. Clients should also enforce and communicate this\nbehavior in the UI.\n\n**Changes**: New in Zulip 11.0 (feature level 382). This API builds on\nthe `moderation_request_channel` realm setting, which was added in\nfeature level 331.\n", + "parameters": [ + { + "$ref": "#/components/parameters/MessageId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "report_type": { + "description": "The reason that best describes why the current user is reporting the\ntarget message for moderation.\n", + "type": "string", + "enum": [ + "spam", + "harassment", + "inappropriate", + "norms", + "other" + ], + "example": "harassment" + }, + "description": { + "description": "A short description with additional context about why the current user\nis reporting the target message for moderation.\n\nClients should limit this string to a maximum length of 1000 characters.\n\nIf the `report_type` parameter is `\"other\"`, this parameter is required,\nand its value cannot be an empty string.\n", + "type": "string", + "example": "This message insults and mocks Frodo, which is against the code of conduct." + } + }, + "required": ["report_type"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Moderation request channel must be specified to enable message reporting.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response for when the organization's moderation\nrequest channel is not configured:\n" + } + ] + } + } + } + } + } + } + }, + "/user_uploads": { + "post": { + "operationId": "upload-file", + "summary": "Upload a file", + "tags": ["messages"], + "description": "[Upload](/help/share-and-upload-files) a single file and get the corresponding URL.\n\nInitially, only you will be able to access the link. To share the\nuploaded file, you'll need to [send a message][send-message]\ncontaining the resulting link. Users who can already access the link\ncan reshare it with other users by sending additional Zulip messages\ncontaining the link.\n\nThe maximum allowed file size is available in the `max_file_upload_size_mib`\nfield in the [`POST /register`](/api/register-queue) response. Note that\nlarge files (25MB+) may fail to upload using this API endpoint due to\nnetwork-layer timeouts, depending on the quality of your connection to the\nZulip server.\n\nFor uploading larger files, `/api/v1/tus` is an endpoint implementing the\n[`tus` resumable upload protocol](https://tus.io/protocols/resumable-upload),\nwhich supports uploading arbitrarily large files limited only by the server's\n`max_file_upload_size_mib` (Configured via `MAX_FILE_UPLOAD_SIZE` in\n`/etc/zulip/settings.py`). Clients which send authenticated credentials\n(either via browser-based cookies, or API key via `Authorization` header) may\nuse this endpoint to upload files.\n\n**Changes**: The `api/v1/tus` endpoint supporting resumable uploads was\nintroduced in Zulip 10.0 (feature level 296). Previously,\n`max_file_upload_size_mib` was typically 25MB.\n\n[uploaded-files]: /help/manage-your-uploaded-files\n[send-message]: /api/send-message\n", + "x-parameter-description": "As described above, the file to upload must be provided in the\nrequest's body.\n\n[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings\n", + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "filename": { + "type": "string", + "format": "binary", + "example": "/path/to/file" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "uri": { + "type": "string", + "deprecated": true, + "description": "The URL of the uploaded file. Alias of `url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 272). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" + }, + "url": { + "type": "string", + "description": "The URL of the uploaded file.\n\n**Changes**: New in Zulip 9.0 (feature level 272). Previously,\nthis property was only available under the legacy `uri` name.\n" + }, + "filename": { + "type": "string", + "description": "The filename that Zulip stored the upload as. This usually\ndiffers from the basename of the URL when HTML escaping is\nrequired to generate a valid URL.\n\nClients generating a Markdown link to a newly uploaded file\nshould do so by combining the `url` and `filename` fields in the\nresponse as follows: `[{filename}]({url})`, with care taken to\nclean `filename` of `[` and `]` characters that might break\nMarkdown rendering.\n\n**Changes**: New in Zulip 10.0 (feature level 285).\n" + } + }, + "example": { + "msg": "", + "result": "success", + "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", + "url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", + "filename": "zulip.txt" + } + } + ] + } + } + } + } + } + } + }, + "/user_uploads/{realm_id_str}/{filename}": { + "get": { + "operationId": "get-file-temporary-url", + "summary": "Get public temporary URL for an uploaded file", + "tags": ["messages"], + "description": "Get a temporary URL for access to an [uploaded file](/api/upload-file)\nthat doesn't require authentication.\n\nThe `SIGNED_ACCESS_TOKEN_VALIDITY_IN_SECONDS` server setting controls\nthe valid length of time for temporary access, which generally is set\nto a default of 60 seconds. Consumers of this API are expected to\nimmediately request the URL that it returns, and should not store it\nin any way.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", + "parameters": [ + { + "name": "realm_id_str", + "in": "path", + "description": "The ID of the Zulip organization.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + }, + { + "name": "filename", + "in": "path", + "description": "Path to the [uploaded file](/api/upload-file).\n", + "schema": { + "type": "string" + }, + "example": "4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", + "required": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "url": { + "type": "string", + "description": "A temporary URL that can be used to access the uploaded file\nwithout Zulip's normal API authentication.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55" + } + } + ] + } + } + } + } + } + } + }, + "/users": { + "get": { + "operationId": "get-users", + "summary": "Get users", + "tags": ["users"], + "description": "Retrieve details on users in the organization.\n\nBy default, returns all accessible users in the organization.\nThe `user_ids` query parameter can be used to limit the\nresults to a specific set of user IDs.\n\nOptionally includes values of [custom profile fields](/help/custom-profile-fields).\n\nYou can also [fetch details on a single user](/api/get-user).\n\n**Changes**: This endpoint did not support unauthenticated\naccess in organizations using the [public access\noption](/help/public-access-option) prior to Zulip 11.0\n(feature level 387).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": [""] + } + }, + { + "type": "exclude", + "parameters": { + "enum": [""] + }, + "description": "You may pass the `client_gravatar` query parameter as follows:\n" + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/ClientGravatar" + }, + { + "$ref": "#/components/parameters/IncludeCustomProfileFields" + }, + { + "name": "user_ids", + "in": "query", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "integer" + } + }, + "example": [1, 2, 3] + } + }, + "required": false, + "description": "Limits the results to the specified user IDs. If not\nprovided, the server will return all accessible users in\nthe organization.\n\n**Changes**: New in Zulip 11.0 (feature level 384).\n" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "members": { + "type": "array", + "description": "A list of `user` objects, each containing details about a user in the\norganization.\n", + "items": { + "$ref": "#/components/schemas/User" + } + } + }, + "example": { + "msg": "", + "result": "success", + "members": [ + { + "is_active": true, + "email": "AARON@zulip.com", + "delivery_email": null, + "is_admin": false, + "is_owner": false, + "role": 400, + "avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1", + "bot_type": null, + "timezone": "", + "is_bot": false, + "user_id": 7, + "profile_data": {}, + "is_guest": false, + "date_joined": "2019-10-20T07:50:53.728864+00:00", + "full_name": "aaron" + }, + { + "date_joined": "2019-10-20T07:50:53.729659+00:00", + "full_name": "King Hamlet", + "is_guest": false, + "profile_data": { + "4": { + "value": "0" + }, + "2": { + "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", + "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" + }, + "5": { + "value": "1900-01-01" + }, + "7": { + "value": "[11]" + }, + "6": { + "value": "https://blog.zulig.org" + }, + "1": { + "value": "+0-11-23-456-7890", + "rendered_value": "

+0-11-23-456-7890

" + }, + "8": { + "value": "zulipbot" + }, + "3": { + "rendered_value": "

Dark chocolate

", + "value": "Dark chocolate" + } + }, + "user_id": 10, + "is_bot": false, + "bot_type": null, + "timezone": "", + "is_admin": false, + "is_owner": false, + "role": 400, + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "is_active": true, + "email": "hamlet@zulip.com", + "delivery_email": null + }, + { + "bot_owner_id": 11, + "is_guest": false, + "date_joined": "2019-10-20T12:52:17.862053+00:00", + "full_name": "Iago's Bot", + "email": "iago-bot@zulipdev.com", + "delivery_email": "iago-bot@zulipdev.com", + "is_active": true, + "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", + "is_admin": false, + "is_owner": false, + "role": 400, + "user_id": 23, + "bot_type": 1, + "timezone": "", + "is_bot": true + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "create-user", + "summary": "Create a user", + "tags": ["users"], + "description": "Create a new user account via the API.\n\n!!! warn \"\"\n\n **Note**: On Zulip Cloud, this feature is available only for\n organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)\n or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators\n can request the required `can_create_users` permission for a bot or\n user by contacting [Zulip Cloud support][support] with an\n explanation for why it is needed. Self-hosted installations can\n toggle `can_create_users` on an account using the `manage.py\n change_user_role` [management command][management-commands].\n\n**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was\navailable to all organization administrators.\n\n[support]: /help/contact-support\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n", + "x-requires-administrator": true, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "email": { + "description": "The email address of the new user.\n", + "type": "string", + "example": "username@example.com" + }, + "password": { + "description": "The password of the new user.\n", + "type": "string", + "example": "abcd1234" + }, + "full_name": { + "description": "The full name of the new user.\n", + "type": "string", + "example": "New User" + } + }, + "required": ["email", "password", "full_name"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "user_id": { + "type": "integer", + "description": "The ID assigned to the newly created user.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" + } + }, + "example": { + "msg": "", + "result": "success", + "user_id": 25 + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Email is already in use.", + "result": "error" + }, + "description": "A typical JSON response for when another user with the same\nemail address already exists in the realm:\n" + } + ] + } + } + } + } + } + } + }, + "/users/{user_id}/reactivate": { + "post": { + "operationId": "reactivate-user", + "summary": "Reactivate a user", + "tags": ["users"], + "x-requires-administrator": true, + "description": "[Reactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/users/{user_id}/status": { + "post": { + "operationId": "update-status-for-user", + "summary": "Update user status", + "tags": ["users"], + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + } + ], + "description": "Administrator endpoint for changing the [status](/help/status-and-availability) of\nanother user.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n", + "x-requires-administrator": true, + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "status_text": { + "type": "string", + "description": "The text content of the status message. Sending the empty string\nwill clear the user's status.\n\n**Note**: The limit on the size of the message is 60 characters.\n", + "example": "on vacation" + }, + "emoji_name": { + "type": "string", + "description": "The name for the emoji to associate with this status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "car" + }, + "emoji_code": { + "type": "string", + "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "1f697" + }, + "reaction_type": { + "type": "string", + "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "unicode_emoji" + } + } + }, + "encoding": { + "away": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Insufficient permission", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response user making request does not have permission to update other user's status.:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Client did not pass any new values.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when no changes were requested:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "status_text is too long (limit: 60 characters)", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the\n`status_text` message exceeds the limit of\n60 characters:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when `emoji_name` is not specified\nbut `emoji_code` or `reaction_type` is specified:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Emoji 'invalid' does not exist", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the emoji name does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid emoji name.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the emoji name is invalid:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid custom emoji.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the custom emoji is invalid:\n" + } + ] + } + ] + } + } + } + } + } + }, + "get": { + "operationId": "get-user-status", + "summary": "Get a user's status", + "tags": ["users"], + "description": "Get the [status](/help/status-and-availability) currently set by a\nuser in the organization.\n\n**Changes**: New in Zulip 9.0 (feature level 262). Previously,\nuser statuses could only be fetched via the [`POST\n/register`](/api/register-queue) endpoint.\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "status": { + "allOf": [ + { + "description": "The status set by the user. Note that, if the user doesn't have a status\ncurrently set, then the returned dictionary will be empty as none of the\nkeys listed below will be present.\n" + }, + { + "$ref": "#/components/schemas/UserStatus" + } + ] + } + }, + "example": { + "result": "success", + "msg": "", + "status": { + "status_text": "on vacation", + "emoji_name": "car", + "emoji_code": "1f697", + "reaction_type": "unicode_emoji" + } + } + } + ] + } + } + } + }, + "400": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "No such user", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the user does not exist:\n" + } + ] + } + } + } + } + } + } + }, + "/users/{user_id_or_email}/presence": { + "get": { + "operationId": "get-user-presence", + "summary": "Get a user's presence", + "tags": ["users"], + "description": "Get the presence status for a specific user.\n\nThis endpoint is most useful for embedding data about a user's\npresence status in other sites (e.g. an employee directory). Full\nZulip clients like mobile/desktop apps will want to use the [main\npresence endpoint](/api/get-presence), which returns data for all\nactive users in the organization, instead.\n", + "parameters": [ + { + "name": "user_id_or_email", + "in": "path", + "description": "The ID or Zulip API email address of the user whose presence you want to fetch.\n\n**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported\nidentifying the user by Zulip API email.\n", + "schema": { + "type": "string" + }, + "example": "iago@zulip.com", + "required": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "presence": { + "type": "object", + "description": "An object containing the presence details for the user.\n", + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "properties": { + "timestamp": { + "type": "integer", + "description": "When this update was received. If the timestamp\nis more than a few minutes in the past, the user is offline.\n" + }, + "status": { + "type": "string", + "description": "Whether the user had recently interacted with Zulip at the time\nof the timestamp.\n\nWill be either `\"active\"` or `\"idle\"`\n" + } + }, + "description": "`{client_name}` or `\"aggregated\"`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will always\ncontain two keys, `\"website\"` and `\"aggregated\"`, with identical data. The\nserver no longer stores which client submitted presence updates.\n\nPreviously, the `{client_name}` keys for these objects were the names of the\ndifferent clients where the user was logged in, for example `website` or\n`ZulipDesktop`.\n" + } + } + }, + "example": { + "presence": { + "website": { + "timestamp": 1532697622, + "status": "active" + }, + "aggregated": { + "timestamp": 1532697622, + "status": "active" + } + }, + "result": "success", + "msg": "" + } + } + ] + } + } + } + } + } + } + }, + "/users/me": { + "get": { + "operationId": "get-own-user", + "summary": "Get own user", + "tags": ["users"], + "description": "Get basic data about the user/bot that requests this endpoint.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was\nreplaced by the `can_manage_billing_group` realm setting.\n", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "avatar_url": { + "type": "string", + "description": "URL for the requesting user's avatar.\n\n**Changes**: New in Zulip 2.1.0.\n", + "example": "x" + }, + "avatar_version": { + "type": "integer", + "description": "Version for the requesting user's avatar. Used for cache-busting requests\nfor the user's avatar. Clients generally shouldn't need to use this;\nmost avatar URLs sent by Zulip will already end with `?v={avatar_version}`.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", + "example": 1 + }, + "email": { + "type": "string", + "description": "Zulip API email of the requesting user.\n", + "example": "iago@zulip.com" + }, + "full_name": { + "type": "string", + "description": "Full name of the requesting user.\n", + "example": "Iago" + }, + "is_admin": { + "type": "boolean", + "description": "A boolean indicating if the requesting user is an admin.\n", + "example": true + }, + "is_owner": { + "type": "boolean", + "description": "A boolean indicating if the requesting user is\nan organization owner.\n\n**Changes**: New in Zulip 3.0 (feature level 8).\n", + "example": false + }, + "role": { + "type": "integer", + "enum": [100, 200, 300, 400, 600], + "description": "[Organization-level role](/api/roles-and-permissions) of\nthe requesting user.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" + }, + "is_guest": { + "type": "boolean", + "description": "A boolean indicating if the requesting user is a guest.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", + "example": false + }, + "is_bot": { + "type": "boolean", + "description": "A boolean indicating if the requesting user is a bot.\n", + "example": false + }, + "is_active": { + "type": "boolean", + "description": "A boolean specifying whether the requesting user account\nhas been deactivated.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", + "example": true + }, + "timezone": { + "type": "string", + "description": "The IANA identifier of the requesting user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", + "example": "" + }, + "date_joined": { + "type": "string", + "description": "The time the requesting user's account was created.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", + "example": "2019-10-20T07:50:53.728864+00:00" + }, + "max_message_id": { + "type": "integer", + "deprecated": true, + "description": "The integer ID of the last message received by the requesting\nuser's account.\n\n**Deprecated**. We plan to remove this in favor of recommending\nusing `GET /messages` with `\"anchor\": \"newest\"`.\n", + "example": 30 + }, + "user_id": { + "type": "integer", + "description": "The user's ID.\n", + "example": 1 + }, + "delivery_email": { + "type": "string", + "description": "The requesting user's real email address.\n\n**Changes**: Prior to Zulip 7.0 (feature level 163), this field was\npresent only when `email_address_visibility` was restricted and the\nrequesting user had permission to access realm users' emails. As of\nthis feature level, this field is always present.\n" + }, + "profile_data": { + "$ref": "#/components/schemas/profile_data" + } + }, + "example": { + "avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1", + "avatar_version": 1, + "email": "iago@zulip.com", + "delivery_email": "iago@zulip.com", + "full_name": "Iago", + "is_admin": true, + "is_owner": false, + "role": 200, + "is_guest": false, + "is_bot": false, + "is_active": true, + "timezone": "", + "date_joined": "2019-10-20T07:50:53.728864+00:00", + "max_message_id": 30, + "msg": "", + "result": "success", + "user_id": 5, + "profile_data": { + "5": { + "value": "2000-01-01" + }, + "4": { + "value": "emacs" + }, + "7": { + "value": "[10]" + }, + "1": { + "value": "+1-234-567-8901", + "rendered_value": "

+1-234-567-8901

" + }, + "2": { + "rendered_value": "

Betrayer of Othello.

", + "value": "Betrayer of Othello." + }, + "8": { + "value": "zulip" + }, + "3": { + "value": "Apples", + "rendered_value": "

Apples

" + }, + "6": { + "value": "https://zulip.readthedocs.io/en/latest/" + } + } + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "deactivate-own-user", + "summary": "Deactivate own user", + "tags": ["users"], + "description": "Deactivates the current user's account. See also the administrative endpoint for\n[deactivating another user](/api/deactivate-user).\n\nThis endpoint is primarily useful to Zulip clients providing a user settings UI.\n", + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "entity": { + "type": "string", + "description": "An internationalized string that notes if the current user is the only\norganization owner or the only user in the organization.\n" + }, + "is_last_owner": { + "type": "boolean", + "description": "Whether the current user is the only organization owner (meaning there\nare other active users in the organization) or the only active user in the\norganization.\n" + } + }, + "required": ["entity", "is_last_owner"], + "example": { + "code": "CANNOT_DEACTIVATE_LAST_USER", + "msg": "Cannot deactivate the only organization owner", + "result": "error", + "entity": "organization owner", + "is_last_owner": true + }, + "description": "If the current user is the only organization owner or only user in the\norganization, their account cannot be deactivated and an error response\nwill be returned. The `is_last_owner` field in the error response\nindicates whether the user is the only owner (`true`) or the only user\n(`false`). The `entity` field in the error response is a internationalized\nstring that notes if the current user is the only organization owner or\nthe only user.\n\nAn example JSON error response when the current user is the only\norganization owner in the organization:\n" + } + ] + } + } + } + } + } + } + }, + "/users/me/alert_words": { + "get": { + "operationId": "get-alert-words", + "summary": "Get all alert words", + "tags": ["users"], + "description": "Get all of the user's configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "alert_words": { + "type": "array", + "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", + "items": { + "type": "string" + } + } + }, + "example": { + "result": "success", + "msg": "", + "alert_words": ["natural", "illustrious"] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "add-alert-words", + "summary": "Add alert words", + "tags": ["users"], + "description": "Add words (or phrases) to the user's set of configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "alert_words": { + "description": "An array of strings to be added to the user's set of configured\nalert words. Strings already present in the user's set of alert words\nalready are ignored.\n\nAlert words are case insensitive.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["foo", "bar"] + } + }, + "required": ["alert_words"] + }, + "encoding": { + "alert_words": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "alert_words": { + "type": "array", + "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", + "items": { + "type": "string" + } + } + }, + "example": { + "result": "success", + "msg": "", + "alert_words": ["foo", "bar", "natural", "illustrious"] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "alert_words[0] is too long (limit: 100 characters)", + "result": "error" + }, + "description": "An example JSON response for when a supplied alert word (or phrase)\nexceeds the character limit:\n" + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "remove-alert-words", + "summary": "Remove alert words", + "tags": ["users"], + "description": "Remove words (or phrases) from the user's set of configured [alert words][alert-words].\n\nAlert words are case insensitive.\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "alert_words": { + "description": "An array of strings to be removed from the user's set of configured\nalert words. Strings that are not in the user's set of alert words\nare ignored.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["foo"] + } + }, + "required": ["alert_words"] + }, + "encoding": { + "alert_words": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "alert_words": { + "type": "array", + "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", + "items": { + "type": "string" + } + } + }, + "example": { + "result": "success", + "msg": "", + "alert_words": ["bar", "natural", "illustrious"] + } + } + ] + } + } + } + } + } + } + }, + "/users/me/presence": { + "post": { + "operationId": "update-presence", + "summary": "Update your presence", + "tags": ["users"], + "description": "Update the current user's [presence][availability] and fetch presence data\nof other users in the organization.\n\nThis endpoint is meant to be used by clients for both:\n\n- Reporting the current user's presence status (`\"active\"` or `\"idle\"`)\n to the server.\n\n- Obtaining the presence data of all other users in the organization via\n regular polling.\n\nAccurate user presence is one of the most expensive parts of any\nchat application (in terms of bandwidth and other resources). Therefore,\nit is important that clients implementing Zulip's user presence system\nuse the modern [`last_update_id`](#parameter-last_update_id) protocol to\nminimize fetching duplicate user presence data.\n\nClient apps implementing presence are recommended to also consume [`presence`\nevents](/api/get-events#presence)), in order to learn about newly online users\nimmediately.\n\nThe Zulip server is responsible for implementing [invisible mode][invisible],\nwhich disables sharing a user's presence data. Nonetheless, clients\nshould check the `presence_enabled` field in user objects in order to\ndisplay the current user as online or offline based on whether they are\nsharing their presence information.\n\n**Changes**: As of Zulip 8.0 (feature level 228), if the\n`CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is\n`true`, then user presence data in the response is [limited to users\nthe current user can see/access][limit-visibility].\n\n[limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users\n[invisible]: /help/status-and-availability#invisible-mode\n[availability]: /help/status-and-availability#availability\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "last_update_id": { + "type": "integer", + "description": "The identifier that specifies what presence data the client already\nhas received, which allows the server to only return more recent\nuser presence data.\n\nThis should be set to `-1` during initialization of the client in\norder to fetch all user presence data, unless the client is obtaining\ninitial user presence metadata from the\n[`POST /register`](/api/register-queue) endpoint.\n\nIn subsequent queries to this endpoint, this value should be set to the\nmost recent value of `presence_last_update_id` returned by the server\nin this endpoint's response, which implements incremental fetching\nof user presence data.\n\nWhen this parameter is passed, the user presence data in the response\nwill always be in the modern format.\n\n**Changes**: New in Zulip 9.0 (feature level 263). Previously, the\nserver sent user presence data for all users who had been active in the\nlast two weeks unconditionally.\n", + "example": 5 + }, + "history_limit_days": { + "type": "integer", + "description": "Limits how far back in time to fetch user presence data. If not specified,\ndefaults to 14 days. A value of N means that the oldest presence data\nfetched will be from at most N days ago.\n\nNote that this is only useful during the initial user presence data fetch,\nas subsequent fetches should use the `last_update_id` parameter, which\nwill act as the limit on how much presence data is returned. `history_limit_days`\nis ignored if `last_update_id` is passed with a value greater than `0`,\nindicating that the client already has some presence data.\n\n**Changes**: New in Zulip 10.0 (feature level 288).\n", + "example": 365 + }, + "new_user_input": { + "type": "boolean", + "description": "Whether the user has interacted with the client (e.g. moved the mouse,\nused the keyboard, etc.) since the previous presence request from this\nclient.\n\nThe server uses data from this parameter to implement certain [usage\nstatistics](/help/analytics).\n\nUser interface clients that might run in the background, without the\nuser ever interacting with them, should be careful to only pass `true`\nif the user has actually interacted with the client in order to avoid\ncorrupting usage statistics graphs.\n", + "example": false, + "default": false + }, + "ping_only": { + "type": "boolean", + "description": "Whether the client is sending a ping-only request, meaning it only\nwants to update the user's presence `status` on the server.\n\nOtherwise, also requests the server return user presence data for all\nusers in the organization, which is further specified by the\n[`last_update_id`](#parameter-last_update_id) parameter.\n", + "example": false, + "default": false + }, + "slim_presence": { + "type": "boolean", + "description": "Legacy parameter for configuring the format (modern or legacy) in\nwhich the server will return user presence data for the organization.\n\nModern clients should use\n[`last_update_id`](#parameter-last_update_id), which guarantees that\nuser presence data will be returned in the modern format, and\nshould not pass this parameter as `true` unless interacting with an\nolder server.\n\nLegacy clients that do not yet support `last_update_id` may use the\nvalue of `true` to request the modern format for user presence data.\n\n**Note**: The legacy format for user presence data will be removed\nentirely in a future release.\n\n**Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using\nthe modern `last_update_id` parameter is the recommended way to\nrequest the modern format for user presence data.\n\nNew in Zulip 3.0 (no feature level as it was an unstable API at that\npoint).\n", + "example": false, + "default": false, + "deprecated": true + }, + "status": { + "type": "string", + "enum": ["idle", "active"], + "description": "The status of the user on this client.\n\nClients should report the user as `\"active\"` on this device if the client\nknows that the user is presently using the device (and thus would\npotentially see a notification immediately), even if the user\nhas not directly interacted with the Zulip client.\n\nOtherwise, it should report the user as `\"idle\"`.\n\nSee the related [`new_user_input`](#parameter-new_user_input) parameter\nfor how a client should report whether the user is actively using the\nZulip client.\n", + "example": "active" + } + }, + "required": ["status"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": ["result", "msg"], + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "presence_last_update_id": { + "type": "integer", + "description": "The identifier for the latest user presence data returned in\nthe `presences` data of the response.\n\nIf a value was passed for `last_update_id`, then this is\nguaranteed to be equal to or greater than that value. If it\nis the same value, then that indicates to the client that\nthere were no updates to previously received user presence\ndata.\n\nThe client should then pass this value as the `last_update_id`\nparameter when it next queries this endpoint, in order to only\nreceive new user presence data and avoid redundantly fetching\nalready known information.\n\nThis will be `-1` if no value was passed for\n[`last_update_id`](#parameter-last_update_id) and no user\npresence data was returned by the server. This can happen, for\nexample, if an organization has disabled presence.\n\n**Changes**: New in Zulip 9.0 (feature level 263).\n" + }, + "server_timestamp": { + "type": "number", + "description": "Only present if `ping_only` is `false`.\n\nThe time when the server fetched the `presences` data included\nin the response.\n" + }, + "presences": { + "type": "object", + "description": "Only present if `ping_only` is `false`.\n\nA dictionary where each entry describes the presence details\nof a user in the Zulip organization. Entries can be in either\nthe modern presence format or the legacy presence format.\n\nThese entries will be the modern presence format when the\n`last_updated_id` parameter is passed, or when the deprecated\n`slim_presence` parameter is `true`.\n\nIf the deprecated `slim_presence` parameter is `false` and the\n`last_updated_id` parameter is omitted, the entries will be in\nthe legacy presence API format.\n\n**Note**: The legacy presence format should only be used when\ninteracting with old servers. It will be removed as soon as\ndoing so is practical.\n", + "additionalProperties": { + "description": "Will be one of these two formats (modern or legacy) for user\npresence data:\n", + "oneOf": [ + { + "$ref": "#/components/schemas/ModernPresenceFormat" + }, + { + "type": "object", + "description": "`{user_email}`: Presence data (legacy format) for the user with\nthe specified Zulip API email.\n", + "additionalProperties": { + "$ref": "#/components/schemas/LegacyPresenceFormat" + } + } + ] + } + } + } + } + ] + }, + "examples": { + "modern-presence-format-example": { + "description": "Modern presence format:\n", + "value": { + "msg": "", + "presences": { + "10": { + "idle_timestamp": 1656958530, + "active_timestamp": 1656958520 + } + }, + "result": "success", + "server_timestamp": 1656958539.6287155, + "presence_last_update_id": 1000 + } + }, + "legacy-presence-format-example": { + "description": "Legacy presence format:\n", + "value": { + "msg": "", + "presences": { + "user@example.com": { + "aggregated": { + "client": "website", + "status": "idle", + "timestamp": 1594825445 + }, + "website": { + "client": "website", + "status": "idle", + "timestamp": 1594825445, + "pushable": false + } + } + }, + "result": "success", + "server_timestamp": 1656958539.6287155, + "presence_last_update_id": 1000 + } + } + } + } + } + } + } + } + }, + "/users/me/status": { + "post": { + "operationId": "update-status", + "summary": "Update your status", + "tags": ["users"], + "description": "Change your [status](/help/status-and-availability).\n\nA request to this endpoint will only change the parameters passed.\nFor example, passing just `status_text` requests a change in the status\ntext, but will leave the status emoji unchanged.\n\nClients that wish to set the user's status to a specific value should\npass all supported parameters.\n\n**Changes**: In Zulip 5.0 (feature level 86), added support for\n`emoji_name`, `emoji_code`, and `reaction_type` parameters.\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "status_text": { + "type": "string", + "description": "The text content of the status message. Sending the empty string\nwill clear the user's status.\n\n**Note**: The limit on the size of the message is 60 characters.\n", + "example": "on vacation" + }, + "away": { + "deprecated": true, + "type": "boolean", + "description": "Whether the user should be marked as \"away\".\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n", + "example": true + }, + "emoji_name": { + "type": "string", + "description": "The name for the emoji to associate with this status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "car" + }, + "emoji_code": { + "type": "string", + "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "1f697" + }, + "reaction_type": { + "type": "string", + "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", + "example": "unicode_emoji" + } + } + }, + "encoding": { + "away": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Client did not pass any new values.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when no changes were requested:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "status_text is too long (limit: 60 characters)", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the\n`status_text` message exceeds the limit of\n60 characters:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when `emoji_name` is not specified\nbut `emoji_code` or `reaction_type` is specified:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Emoji 'invalid' does not exist", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the emoji name does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid emoji name.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the emoji name is invalid:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid custom emoji.", + "code": "BAD_REQUEST" + }, + "description": "An example JSON error response when the custom emoji is invalid:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/users/me/{stream_id}/topics": { + "get": { + "operationId": "get-stream-topics", + "summary": "Get topics in a channel", + "tags": ["channels"], + "description": "Get all topics the user has access to in a specific channel.\n\nNote that for [private channels with\nprotected history](/help/channel-permissions#private-channels),\nthe user will only have access to topics of messages sent after they\n[subscribed to](/api/subscribe) the channel. Similarly, a user's\n[bot](/help/bots-overview#bot-type) will only have access to messages\nsent after the bot was subscribed to the channel, instead of when the\nuser subscribed.\n", + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + }, + { + "name": "allow_empty_topic_name", + "in": "query", + "description": "Whether the client supports processing the empty string as\na topic name in the returned data.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously,\nthe empty string was not a valid topic.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "topics": { + "type": "array", + "description": "An array of objects with information about user-accessible\ntopics in the specified channel, sorted by recency (i.e.,\nthe topic with the most recent message is ordered first).\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "max_id": { + "description": "The message ID of the last message sent to this topic.\n", + "type": "integer" + }, + "name": { + "description": "The name of the topic.\n", + "type": "string" + } + } + } + } + }, + "example": { + "msg": "", + "result": "success", + "topics": [ + { + "max_id": 26, + "name": "Denmark3" + }, + { + "max_id": 23, + "name": "Denmark1" + }, + { + "max_id": 6, + "name": "Denmark2" + } + ] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the user is attempting to fetch the topics\nof a non-existing channel (or also a private channel they don't have access to):\n" + } + ] + } + } + } + } + } + } + }, + "/users/me/subscriptions": { + "get": { + "operationId": "get-subscriptions", + "summary": "Get subscribed channels", + "tags": ["channels"], + "description": "Get all channels that the user is subscribed to.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": [""] + } + }, + { + "type": "exclude", + "description": "You may pass the `include_subscribers` query parameter as follows:\n", + "parameters": { + "enum": [""] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/IncludeSubscribers" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": ["subscriptions"], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "subscriptions": { + "type": "array", + "description": "A list of dictionaries where each dictionary contains\ninformation about one of the subscribed channels.\n\n**Changes**: Removed `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n", + "items": { + "$ref": "#/components/schemas/Subscription" + } + } + }, + "example": { + "msg": "", + "result": "success", + "subscriptions": [ + { + "audible_notifications": true, + "color": "#e79ab5", + "creator_id": null, + "description": "A Scandinavian country", + "desktop_notifications": true, + "is_archived": false, + "is_muted": false, + "invite_only": false, + "name": "Denmark", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 1, + "subscribers": [7, 10, 11, 12, 14] + }, + { + "audible_notifications": true, + "color": "#e79ab5", + "creator_id": 8, + "description": "Located in the United Kingdom", + "desktop_notifications": true, + "is_archived": false, + "is_muted": false, + "invite_only": false, + "name": "Scotland", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 3, + "subscribers": [7, 11, 12, 14] + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "subscribe", + "summary": "Subscribe to a channel", + "tags": ["channels"], + "description": "Subscribe one or more users to one or more channels.\n\nIf any of the specified channels do not exist, they are automatically\ncreated. The initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\nNote that the ability to subscribe oneself and/or other users\nto a specified channel depends on the [channel's permissions\nsettings](/help/channel-permissions).\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n\nBefore Zulip 10.0 (feature level 357), the\n`can_subscribe_group` permission, which allows members of the\ngroup to subscribe themselves to the channel, did not exist.\n\nBefore Zulip 10.0 (feature level 349), a user cannot subscribe\nother users to a private channel without being subscribed\nto that channel themselves. Now, If a user is part of\n`can_add_subscribers_group`, they can subscribe themselves or other\nusers to a private channel without being subscribed to that channel.\n\nRemoved `stream_post_policy` and `is_announcement_only`\nparameters in Zulip 10.0 (feature level 333), as permission to post\nin the channel is now controlled by `can_send_message_group`.\n\nBefore Zulip 8.0 (feature level 208), if a user specified by the\n[`principals`][principals-param] parameter was a deactivated user,\nor did not exist, then an HTTP status code of 403 was returned with\n`code: \"UNAUTHORIZED_PRINCIPAL\"` in the error response. As of this\nfeature level, an HTTP status code of 400 is returned with\n`code: \"BAD_REQUEST\"` in the error response for these cases.\n\n[principals-param]: /api/subscribe#parameter-principals\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["subscriptions"] + } + }, + { + "type": "include", + "description": "To subscribe another user to a channel, you may pass in\nthe `principals` parameter, like so:\n", + "parameters": { + "enum": ["subscriptions", "principals"] + } + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "subscriptions": { + "description": "A list of dictionaries containing the key `name` and value\nspecifying the name of the channel to subscribe. If the channel does not\nexist a new channel is created. The description of the channel created can\nbe specified by setting the dictionary key `description` with an\nappropriate value.\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The name of the channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n" + }, + "description": { + "type": "string", + "description": "The [description](/help/change-the-channel-description)\nto use for a new channel being created, in text/markdown format.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n" + } + }, + "required": ["name"], + "example": { + "no-description": { + "value": { + "name": "Verona" + } + }, + "with-description": { + "value": { + "name": "Verona", + "description": "Italian city" + } + } + } + }, + "example": [ + { + "name": "Verona", + "description": "Italian city" + } + ] + }, + "principals": { + "$ref": "#/components/schemas/Principals" + }, + "authorization_errors_fatal": { + "description": "A boolean specifying whether authorization errors (such as when the\nrequesting user is not authorized to access a private channel) should be\nconsidered fatal or not. When `true`, an authorization error is reported\nas such. When set to `false`, the response will be a 200 and any channels\nwhere the request encountered an authorization error will be listed\nin the `unauthorized` key.\n", + "type": "boolean", + "default": true, + "example": false + }, + "announce": { + "description": "If one of the channels specified did not exist previously and is thus created\nby this call, this determines whether [notification bot](/help/configure-automated-notices)\nwill send an announcement about the new channel's creation.\n", + "type": "boolean", + "default": false, + "example": true + }, + "invite_only": { + "description": "As described above, this endpoint will create a new channel if passed\na channel name that doesn't already exist. This parameters and the ones\nthat follow are used to request an initial configuration of a created\nchannel; they are ignored for channels that already exist.\n\nThis parameter determines whether any newly created channels will be\nprivate channels.\n", + "type": "boolean", + "default": false, + "example": true + }, + "is_web_public": { + "description": "This parameter determines whether any newly created channels will be\nweb-public channels.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current use to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 98).\n", + "type": "boolean", + "default": false, + "example": true + }, + "is_default_stream": { + "description": "This parameter determines whether any newly created channels will be\nadded as [default channels][default-channels] for new users joining\nthe organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n\n**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status\ncould only be changed using the [dedicated API endpoint](/api/add-default-stream).\n", + "type": "boolean", + "default": false, + "example": true + }, + "history_public_to_subscribers": { + "$ref": "#/components/schemas/HistoryPublicToSubscribers" + }, + "message_retention_days": { + "$ref": "#/components/schemas/MessageRetentionDays" + }, + "topics_policy": { + "$ref": "#/components/schemas/TopicsPolicy" + }, + "can_add_subscribers_group": { + "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" + }, + "can_remove_subscribers_group": { + "$ref": "#/components/schemas/CanRemoveSubscribersGroup" + }, + "can_administer_channel_group": { + "$ref": "#/components/schemas/CanAdministerChannelGroup" + }, + "can_delete_any_message_group": { + "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" + }, + "can_delete_own_message_group": { + "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" + }, + "can_move_messages_out_of_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" + }, + "can_move_messages_within_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" + }, + "can_send_message_group": { + "$ref": "#/components/schemas/CanSendMessageGroup" + }, + "can_subscribe_group": { + "$ref": "#/components/schemas/CanSubscribeGroup" + }, + "can_resolve_topics_group": { + "$ref": "#/components/schemas/CanResolveTopicsGroup" + }, + "folder_id": { + "description": "This parameter adds the newly created channel to the specified\n[channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "type": "integer", + "example": 1 + }, + "send_new_subscription_messages": { + "$ref": "#/components/schemas/SendNewSubscriptionMessages" + } + }, + "required": ["subscriptions"] + }, + "encoding": { + "subscriptions": { + "contentType": "application/json" + }, + "principals": { + "contentType": "application/json" + }, + "authorization_errors_fatal": { + "contentType": "application/json" + }, + "announce": { + "contentType": "application/json" + }, + "invite_only": { + "contentType": "application/json" + }, + "is_web_public": { + "contentType": "application/json" + }, + "is_default_stream": { + "contentType": "application/json" + }, + "history_public_to_subscribers": { + "contentType": "application/json" + }, + "topics_policy": { + "contentType": "application/json" + }, + "can_add_subscribers_group": { + "contentType": "application/json" + }, + "can_remove_subscribers_group": { + "contentType": "application/json" + }, + "can_administer_channel_group": { + "contentType": "application/json" + }, + "can_delete_any_message_group": { + "contentType": "application/json" + }, + "can_delete_own_message_group": { + "contentType": "application/json" + }, + "can_move_messages_out_of_channel_group": { + "contentType": "application/json" + }, + "can_move_messages_within_channel_group": { + "contentType": "application/json" + }, + "can_send_message_group": { + "contentType": "application/json" + }, + "can_subscribe_group": { + "contentType": "application/json" + }, + "can_resolve_topics_group": { + "contentType": "application/json" + }, + "folder_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "subscribed": { + "type": "object", + "description": "A dictionary where the key is the ID of the user and the value\nis a list of the names of the channels that user was subscribed\nto as a result of the request.\n\n**Changes**: Before Zulip 10.0 (feature level 289), the user\nkeys were Zulip API email addresses, not user ID.\n", + "additionalProperties": { + "description": "`{id}`: List of the names of the channels that were subscribed\nto as a result of the query.\n", + "type": "array", + "items": { + "type": "string" + } + } + }, + "already_subscribed": { + "type": "object", + "description": "A dictionary where the key is the ID of the user and the value\nis a list of the names of the channels that where the user was\nnot added as a subscriber in this request, because they were\nalready a subscriber.\n\n**Changes**: Before Zulip 10.0 (feature level 289), the user\nkeys were Zulip API email addresses, not user IDs.\n", + "additionalProperties": { + "description": "`{id}`: List of the names of the channels that the user is\nalready subscribed to.\n", + "type": "array", + "items": { + "type": "string" + } + } + }, + "unauthorized": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of names of channels that the requesting user/bot was not\nauthorized to subscribe to. Only present if `\"authorization_errors_fatal\": false`.\n" + }, + "new_subscription_messages_sent": { + "type": "boolean", + "description": "Only present if the parameter `send_new_subscription_messages`\nin the request was `true`.\n\nWhether Notification Bot DMs in fact sent to the added\nsubscribers as requested by the `send_new_subscription_messages`\nparameter. Clients may find this value useful to communicate\nwith users about the effect of this request.\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n" + } + }, + "example": { + "already_subscribed": { + "1": ["testing-help"] + }, + "msg": "", + "result": "success", + "subscribed": { + "2": ["testing-help"] + } + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "msg": "Unable to access channel (private).", + "result": "error", + "code": "BAD_REQUEST" + }, + "description": "An example JSON response for when the requesting user does not have\naccess to a private channel and `\"authorization_errors_fatal\": true`:\n" + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "update-subscriptions", + "summary": "Update subscriptions", + "tags": ["channels"], + "description": "Update which channels you are subscribed to.\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "delete": { + "description": "A list of channel names to unsubscribe from.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["Verona", "Denmark"] + }, + "add": { + "description": "A list of objects describing which channels to subscribe to, optionally\nincluding per-user subscription parameters (e.g. color) and if the\nchannel is to be created, its description.\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string" + }, + "color": { + "type": "string" + }, + "description": { + "type": "string" + } + } + }, + "example": [ + { + "name": "Verona" + }, + { + "name": "Denmark", + "color": "#e79ab5", + "description": "A Scandinavian country" + } + ] + } + } + }, + "encoding": { + "delete": { + "contentType": "application/json" + }, + "add": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": [ + "subscribed", + "already_subscribed", + "removed" + ], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "subscribed": { + "type": "object", + "description": "A dictionary where the key is the Zulip API email\naddress of the user/bot and the value is a\nlist of the names of the channels that were\nsubscribed to as a result of the query.\n", + "additionalProperties": { + "description": "`{email_id}`: A list of the names of channels that\nthe user was subscribed to as a result of the query.\n", + "type": "array", + "items": { + "type": "string" + } + } + }, + "already_subscribed": { + "type": "object", + "description": "A dictionary where the key is the Zulip API email\naddress of the user/bot and the value is a\nlist of the names of the channels that the\nuser/bot is already subscribed to.\n", + "additionalProperties": { + "description": "`{email_id}`: A list of the names of channels that\nthe user was already subscribed to.\n", + "type": "array", + "items": { + "type": "string" + } + } + }, + "not_removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of the names of channels that the user\nis already unsubscribed from, and hence\ndoesn't need to be unsubscribed.\n" + }, + "removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of the names of channels which were unsubscribed\nfrom as a result of the query.\n" + }, + "new_subscription_messages_sent": { + "type": "boolean", + "description": "Only present if the parameter `send_new_subscription_messages`\nin the request was `true`.\n\nWhether Notification Bot DMs in fact sent to the added\nsubscribers as requested by the `send_new_subscription_messages`\nparameter. Clients may find this value useful to communicate\nwith users about the effect of this request.\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n" + } + }, + "example": { + "msg": "", + "subscribed": {}, + "already_subscribed": { + "iago@zulip.com": ["Verona"] + }, + "not_removed": [], + "removed": ["testing-help"], + "result": "success" + } + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "unsubscribe", + "summary": "Unsubscribe from a channel", + "tags": ["channels"], + "description": "Unsubscribe yourself or other users from one or more channels.\n\nIn addition to managing the current user's subscriptions, this\nendpoint can be used to remove other users from channels. This\nis possible in 3 situations:\n\n- Organization administrators can remove any user from any\n channel.\n- Users can remove a bot that they own from any channel that\n the user [can access](/help/channel-permissions).\n- Users can unsubscribe any user from a channel if they [have\n access](/help/channel-permissions) to the channel and are a\n member of the [user group](/api/get-user-groups) specified\n by the [`can_remove_subscribers_group`][can-remove-parameter]\n for the channel.\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n\nBefore Zulip 8.0 (feature level 208), if a user specified by\nthe [`principals`][principals-param] parameter was a\ndeactivated user, or did not exist, then an HTTP status code\nof 403 was returned with `code: \"UNAUTHORIZED_PRINCIPAL\"` in\nthe error response. As of this feature level, an HTTP status\ncode of 400 is returned with `code: \"BAD_REQUEST\"` in the\nerror response for these cases.\n\nBefore Zulip 8.0 (feature level 197),\nthe `can_remove_subscribers_group` setting\nwas named `can_remove_subscribers_group_id`.\n\nBefore Zulip 7.0 (feature level 161), the\n`can_remove_subscribers_group_id` for all channels was always\nthe system group for organization administrators.\n\nBefore Zulip 6.0 (feature level 145), users had no special\nprivileges for managing bots that they own.\n\n[principals-param]: /api/unsubscribe#parameter-principals\n[can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "description": "**Note**: Unsubscribing another user from a channel requires\nadministrative privileges.\n", + "parameters": { + "enum": ["subscriptions"] + } + }, + { + "type": "exclude", + "parameters": { + "enum": [""] + }, + "description": "You may specify the `principals` parameter like so:\n" + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "subscriptions": { + "description": "A list of channel names to unsubscribe from. This parameter is called\n`streams` in our Python API.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["Verona", "Denmark"] + }, + "principals": { + "$ref": "#/components/schemas/Principals" + } + }, + "required": ["subscriptions"] + }, + "encoding": { + "subscriptions": { + "contentType": "application/json" + }, + "principals": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "not_removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of the names of channels that the user is already unsubscribed\nfrom, and hence doesn't need to be unsubscribed.\n" + }, + "removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of the names of channels which were unsubscribed from as a result\nof the query.\n" + } + }, + "example": { + "msg": "", + "not_removed": [], + "removed": ["testing-help"], + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/NonExistingChannelNameError" + }, + { + "description": "A typical failed JSON response for when the target channel does not exist:\n" + } + ] + } + } + } + } + } + } + }, + "/users/me/subscriptions/muted_topics": { + "patch": { + "deprecated": true, + "operationId": "mute-topic", + "summary": "Topic muting", + "tags": ["channels"], + "description": "[Mute or unmute a topic](/help/mute-a-topic) within a channel that\nthe current user is subscribed to.\n\n**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting\nto newer servers should use the [POST /user_topics](/api/update-user-topic)\nendpoint, as this endpoint may be removed in a future release.\n\nBefore Zulip 7.0 (feature level 169), this endpoint\nreturned an error if asked to mute a topic that was already muted\nor asked to unmute a topic that had not previously been muted.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["stream_id"] + } + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the channel to access.\n\nClients must provide either `stream` or `stream_id` as a parameter\nto this endpoint, but not both.\n\n**Changes**: New in Zulip 2.0.0.\n", + "type": "integer", + "example": 43 + }, + "stream": { + "description": "The name of the channel to access.\n\nClients must provide either `stream` or `stream_id` as a parameter\nto this endpoint, but not both. Clients should use `stream_id`\ninstead of the `stream` parameter when possible.\n", + "type": "string", + "example": "Denmark" + }, + "topic": { + "description": "The topic to (un)mute. Note that the request will succeed regardless of\nwhether any messages have been sent to the specified topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n", + "type": "string", + "example": "dinner" + }, + "op": { + "description": "Whether to mute (`add`) or unmute (`remove`) the provided topic.\n", + "type": "string", + "enum": ["add", "remove"], + "example": "add" + } + }, + "required": ["topic", "op"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/mobile_push/test_notification": { + "post": { + "deprecated": true, + "operationId": "test-notify", + "summary": "Send a test notification to mobile device(s)", + "tags": ["mobile"], + "description": "Trigger sending a test push notification to the user's\nselected mobile device or all of their mobile devices.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 420).\nClients connecting to newer servers and with E2EE push\nnotifications support should use the\n[Send an E2EE test notification to mobile device(s)](/api/e2ee-test-notify)\nendpoint, as this endpoint will be removed in a future release.\n\nStarting with Zulip 8.0 (feature level 234), test\nnotifications sent via this endpoint use `test` rather than\n`test-by-device-token` in the `event` field. Also, as of this\nfeature level, all mobile push notifications now include a\n`realm_name` field.\n\nNew in Zulip 8.0 (feature level 217).\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token": { + "description": "The push token for the device to which to send the test notification.\n\nIf this parameter is not submitted, the test notification will be sent\nto all of the user's devices registered on the server.\n\nA mobile client should pass this parameter, to avoid triggering a test\nnotification for other clients.\n", + "type": "string", + "example": "111222" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/JsonSuccess" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/InvalidPushDeviceTokenError" + }, + { + "$ref": "#/components/schemas/InvalidRemotePushDeviceTokenError" + } + ] + } + } + } + } + } + } + }, + "/mobile_push/e2ee/test_notification": { + "post": { + "operationId": "e2ee-test-notify", + "summary": "Send an E2EE test notification to mobile device(s)", + "tags": ["mobile"], + "description": "Trigger sending an end-to-end encrypted (E2EE) test push notification\nto the user's selected mobile device or all of their mobile devices.\n\n**Changes**: New in Zulip 11.0 (feature level 420).\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "push_account_id": { + "description": "The push account ID for the device to which to send the test notification.\n\nIf this parameter is not submitted, the E2EE test notification will\nbe sent to all of the user's devices registered on the server.\n\nA mobile client should pass this parameter, to avoid triggering a test\nnotification for other clients.\n\nSee [`POST /mobile_push/register`](/api/register-push-device)\nfor details on push account IDs.\n", + "type": "integer", + "example": 111222 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/JsonSuccess" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/NoActivePushDeviceError" + } + ] + } + } + } + }, + "403": { + "description": "Forbidden.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/PushNotificationAdminActionRequiredError" + } + ] + } + } + } + }, + "502": { + "description": "Bad gateway.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/FailedToConnectBouncerError" + }, + { + "$ref": "#/components/schemas/InternalBouncerServerError" + } + ] + } + } + } + } + } + } + }, + "/mobile_push/register": { + "post": { + "operationId": "register-push-device", + "summary": "Register E2EE push device", + "tags": ["mobile"], + "description": "Register a device to receive end-to-end encrypted mobile push notifications.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token_kind": { + "description": "Whether the token was generated by FCM or APNs.\n", + "type": "string", + "enum": ["fcm", "apns"], + "example": "fcm" + }, + "push_account_id": { + "description": "A random integer generated by the client that will be included\nin mobile push notifications along with encrypted payloads to\nidentify pushes as being related to this registration.\nMust be unique in the client's table of accounts.\n", + "type": "integer", + "example": 2408 + }, + "push_public_key": { + "description": "Public part of the asymmetric key pair generated by the client\nusing NaCl (the Networking and Cryptography Library), encoded\nusing a RFC 4648 standard base64 encoder.\n\nIt is used to encrypt notifications for delivery to the client.\n", + "type": "string", + "example": "push-public-key" + }, + "bouncer_public_key": { + "description": "Which of the bouncer's public keys the client used to encrypt the\n`PushRegistration` dictionary.\n\nWhen the bouncer rotates the key, a new asymmetric key pair is created,\nand the new public key is baked into a new client release. Because\nthe bouncer routinely rotates key, this field clarifies which\npublic key the client is using.\n", + "type": "string", + "example": "bouncer-public-key" + }, + "encrypted_push_registration": { + "description": "Ciphertext generated by encrypting a `PushRegistration` dictionary\nusing the `bouncer_public_key`, encoded using a RFC 4648 standard\nbase64 encoder.\n\nThe `PushRegistration` dictionary contains the fields `token`,\n`token_kind`, `timestamp`, and (for iOS devices) `ios_app_id`.\nThe dictionary is JSON-encoded before encryption.\n", + "type": "string", + "example": "encrypted-push-registration-data" + } + }, + "required": [ + "token_kind", + "push_account_id", + "push_public_key", + "bouncer_public_key", + "encrypted_push_registration" + ] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Server is not configured to use push notification service.", + "code": "PUSH_SERVICE_NOT_CONFIGURED" + }, + "description": "Error when the server is not configured to use push notification service:\n" + } + ] + } + } + } + } + } + } + }, + "/remotes/push/e2ee/register": { + "post": { + "operationId": "register-remote-push-device", + "summary": "Register E2EE push device to bouncer", + "tags": ["mobile"], + "description": "Register a push device to bouncer to receive end-to-end encrypted\nmobile push notifications.\n\nSelf-hosted servers use this endpoint to asynchronously register\na push device to the bouncer server after receiving a request from\nthe mobile client to [register E2EE push device](/api/register-push-device).\n\nIt is not meant to be used by mobile clients directly.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "realm_uuid": { + "description": "The UUID of the realm to which the push device\nbeing registered belongs.\n", + "type": "string", + "example": "9aa61d0b-8ce5-488d-8e9e-fedc346e6836" + }, + "push_account_id": { + "description": "The `push_account_id` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", + "type": "integer", + "example": 2408 + }, + "encrypted_push_registration": { + "description": "The `encrypted_push_registration` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", + "type": "string", + "example": "encrypted-push-registration-data" + }, + "bouncer_public_key": { + "description": "The `bouncer_public_key` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", + "type": "string", + "example": "bouncer-public-key" + } + }, + "required": [ + "realm_uuid", + "push_account_id", + "encrypted_push_registration", + "bouncer_public_key" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": ["device_id"], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "device_id": { + "type": "integer", + "description": "Unique identifier assigned by the bouncer for the registration.\n", + "example": 2408 + } + }, + "example": { + "device_id": 2408, + "msg": "", + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "INVALID_BOUNCER_PUBLIC_KEY", + "msg": "Invalid bouncer_public_key", + "result": "error" + }, + "description": "An example JSON response for when the given `bouncer_public_key` is invalid:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "REQUEST_EXPIRED", + "msg": "Request expired", + "result": "error" + }, + "description": "An example JSON response for when the given `encrypted_push_registration` is stale:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid encrypted_push_registration", + "result": "error" + }, + "description": "An example JSON response for when either the bouncer fails to decrypt\nthe given `encrypted_push_registration` or the decrypted data is invalid:\n" + } + ] + } + ] + } + } + } + }, + "403": { + "description": "Forbidden.\n", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "MISSING_REMOTE_REALM", + "msg": "Organization not registered", + "result": "error" + }, + "description": "An example JSON response for when no realm is registered for\nthe authenticated server on the bouncer for the given `realm_uuid`:\n" + } + ] + } + } + } + } + } + } + }, + "/user_topics": { + "post": { + "operationId": "update-user-topic", + "summary": "Update personal preferences for a topic", + "tags": ["channels"], + "description": "This endpoint is used to update the personal preferences for a topic,\nsuch as the topic's visibility policy, which is used to implement\n[mute a topic](/help/mute-a-topic) and related features.\n\nThis endpoint can be used to update the visibility policy for the single\nchannel and topic pair indicated by the parameters for a user.\n\n**Changes**: New in Zulip 7.0 (feature level 170). Previously,\ntoggling whether a topic was muted or unmuted was managed by the\n[PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "stream_id": { + "description": "The ID of the channel to access.\n", + "type": "integer", + "example": 1 + }, + "topic": { + "description": "The topic for which the personal preferences needs to be updated.\nNote that the request will succeed regardless of whether\nany messages have been sent to the specified topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", + "type": "string", + "example": "dinner" + }, + "visibility_policy": { + "description": "Controls which visibility policy to set.\n\n- 0 = None. Removes the visibility policy previously set for the topic.\n- 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a channel.\n- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted channel.\n- 3 = Followed. [Follows the topic](/help/follow-a-topic).\n\nIn an unmuted channel, a topic visibility policy of unmuted will have the\nsame effect as the \"None\" visibility policy.\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n", + "type": "integer", + "enum": [0, 1, 2, 3], + "example": 1 + } + }, + "required": ["stream_id", "topic", "visibility_policy"] + }, + "encoding": { + "stream_id": { + "contentType": "application/json" + }, + "visibility_policy": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/users/me/muted_users/{muted_user_id}": { + "post": { + "operationId": "mute-user", + "summary": "Mute a user", + "tags": ["users"], + "description": "[Mute a user](/help/mute-a-user) from the perspective of the requesting\nuser. Messages sent by muted users will be automatically marked as read\nand hidden for the user who muted them.\n\nMuted users should be implemented by clients as follows:\n\n- The server will immediately mark all messages sent by the muted\n user as read. This will automatically clear any existing mobile\n push notifications related to the muted user.\n- The server will mark any new messages sent by the muted user as read\n for the requesting user's account, which prevents all email and mobile\n push notifications.\n- Clients should exclude muted users from presence lists or other UI\n for viewing or composing one-on-one direct messages. One-on-one direct\n messages sent by muted users should be hidden everywhere in the Zulip UI.\n- Channel messages and group direct messages sent by the muted\n user should avoid displaying the content and name/avatar,\n but should display that N messages by a muted user were\n hidden (so that it is possible to interpret the messages by\n other users who are talking with the muted user).\n- Group direct message conversations including the muted user\n should display muted users as \"Muted user\", rather than\n showing their name, in lists of such conversations, along with using\n a blank grey avatar where avatars are displayed.\n- Administrative/settings UI elements for showing \"All users that exist\n on this channel or realm\", e.g. for organization\n administration or showing channel subscribers, should display\n the user's name as normal.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", + "parameters": [ + { + "$ref": "#/components/parameters/MutedUserId" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Cannot mute self", + "result": "error" + }, + "description": "An example JSON response for when the user ID is the current\nuser's ID:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "No such user", + "result": "error" + }, + "description": "An example JSON response for when the user is nonexistent or inaccessible:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "User already muted", + "result": "error" + }, + "description": "An example JSON response for when the user is already muted:\n" + } + ] + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "unmute-user", + "summary": "Unmute a user", + "tags": ["users"], + "description": "[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users)\nfrom the perspective of the requesting user.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", + "parameters": [ + { + "$ref": "#/components/parameters/MutedUserId" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "No such user", + "result": "error" + }, + "description": "An example JSON response for when the user is nonexistent or inaccessible:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "User is not muted", + "result": "error" + }, + "description": "An example JSON response for when the user is not previously muted:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/users/me/apns_device_token": { + "post": { + "deprecated": true, + "operationId": "add-apns-token", + "summary": "Add an APNs device token", + "tags": ["users"], + "description": "This endpoint adds an APNs device token to register for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token": { + "description": "The token provided by the device.\n", + "type": "string", + "example": "c0ffee" + }, + "appid": { + "description": "The ID of the Zulip app that is making the request.\n\n**Changes**: In Zulip 8.0 (feature level 223), this parameter was made\nrequired. Previously, if it was unspecified, the server would use a default\nvalue (based on the `ZULIP_IOS_APP_ID` server setting, which\ndefaulted to `\"org.zulip.Zulip\"`).\n", + "type": "string", + "example": "org.zulip.Zulip" + } + }, + "required": ["token", "appid"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when the token's length is invalid\nor it is empty:\n", + "example": { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST" + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invalid APNS token", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for when the APNs token is invalid:\n" + } + ] + } + ] + } + } + } + } + } + }, + "delete": { + "deprecated": true, + "operationId": "remove-apns-token", + "summary": "Remove an APNs device token", + "tags": ["users"], + "description": "This endpoint removes an APNs device token for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that registration.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token": { + "description": "The token provided by the device.\n", + "type": "string", + "example": "c0ffee" + } + }, + "required": ["token"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when the token's length is invalid\nor it is empty:\n", + "example": { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST" + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Token does not exist", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for when the token does not exist:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/users/me/android_gcm_reg_id": { + "post": { + "deprecated": true, + "operationId": "add-fcm-token", + "summary": "Add an FCM registration token", + "tags": ["users"], + "description": "This endpoint adds an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token": { + "description": "The token provided by the device.\n", + "type": "string", + "example": "android-token" + } + }, + "required": ["token"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when the token's length is invalid\nor is empty:\n", + "example": { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST" + } + } + ] + } + } + } + } + } + }, + "delete": { + "deprecated": true, + "operationId": "remove-fcm-token", + "summary": "Remove an FCM registration token", + "tags": ["users"], + "description": "This endpoint removes an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that registration.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "token": { + "description": "The token provided by the device.\n", + "type": "string", + "example": "android-token" + } + }, + "required": ["token"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "A typical failed JSON response for when the token's length is invalid\nor is empty:\n", + "example": { + "result": "error", + "msg": "Empty or invalid length token", + "code": "BAD_REQUEST" + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Token does not exist", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for when the token does not exist:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/users/{user_id}/subscriptions/{stream_id}": { + "get": { + "operationId": "get-subscription-status", + "summary": "Get subscription status", + "tags": ["channels"], + "description": "Check whether a user is subscribed to a channel.\n\n**Changes**: New in Zulip 3.0 (feature level 12).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + }, + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "is_subscribed": { + "type": "boolean", + "description": "Whether the user is subscribed to the channel.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "is_subscribed": false + } + } + ] + } + } + } + } + } + } + }, + "/realm/emoji/{emoji_name}": { + "post": { + "operationId": "upload-custom-emoji", + "summary": "Upload custom emoji", + "tags": ["server_and_organizations"], + "description": "This endpoint is used to upload a custom emoji for use in the user's\norganization. Access to this endpoint depends on the\n[organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji).\n", + "x-parameter-description": "As described above, the image file to upload must be provided in the\nrequest's body.\n\n## Maximum file size\n\nThe maximum file size for uploads can be configured by the\nadministrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB`\nin the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults\nto 5MB.\n\n[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings\n", + "parameters": [ + { + "name": "emoji_name", + "required": true, + "in": "path", + "description": "The name that should be associated with the uploaded emoji image/gif.\nThe emoji name can only contain letters, numbers, dashes, and spaces.\nUpper and lower case letters are treated the same, and underscores (\\_)\nare treated the same as spaces (consistent with how the Zulip UI\nhandles emoji).\n", + "schema": { + "type": "string" + }, + "example": "smile" + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "filename": { + "type": "string", + "format": "binary", + "example": "/path/to/img.png" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + }, + "delete": { + "operationId": "deactivate-custom-emoji", + "summary": "Deactivate custom emoji", + "tags": ["server_and_organizations"], + "description": "[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from\nthe user's organization.\n\nUsers can only deactivate custom emoji that they added themselves except for\norganization administrators, who can deactivate any custom emoji.\n\nNote that deactivated emoji will still be visible in old messages, reactions,\nuser statuses and channel descriptions.\n\n**Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an\nHTTP status code of 400 when the emoji did not exist, instead of 404.\n", + "parameters": [ + { + "name": "emoji_name", + "required": true, + "in": "path", + "description": "The name of the custom emoji to deactivate.\n", + "schema": { + "type": "string" + }, + "example": "green_tick" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "description": "An example JSON response for when no emoji exists with the provided name:\n", + "example": { + "code": "BAD_REQUEST", + "result": "error", + "msg": "Emoji 'green_tick' does not exist" + } + } + ] + } + } + } + } + } + } + }, + "/realm/emoji": { + "get": { + "operationId": "get-custom-emoji", + "summary": "Get all custom emoji", + "tags": ["server_and_organizations"], + "description": "Get all the custom emoji in the user's organization.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "emoji": { + "type": "object", + "description": "An object that contains `emoji` objects, each identified with their\nemoji ID as the key.\n", + "additionalProperties": { + "$ref": "#/components/schemas/RealmEmoji" + } + } + }, + "example": { + "result": "success", + "msg": "", + "emoji": { + "1": { + "id": "1", + "name": "green_tick", + "source_url": "/user_avatars/1/emoji/images/1.png", + "deactivated": false, + "author_id": 5 + } + } + } + } + ] + } + } + } + } + } + } + }, + "/realm/presence": { + "get": { + "operationId": "get-presence", + "summary": "Get presence of all users", + "tags": ["server_and_organizations"], + "description": "Get the presence information of all the users in an organization.\n\nIf the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level\nsetting is set to `true`, presence information of only accessible\nusers are returned.\n\nComplete Zulip apps are recommended to fetch presence\ninformation when they post their own state using the [`POST\n/presence`](/api/update-presence) API endpoint.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "server_timestamp": { + "type": "number", + "description": "The time when the server fetched the `presences` data included\nin the response.\n" + }, + "presences": { + "type": "object", + "description": "A dictionary where each entry describes the presence details\nof a user in the Zulip organization.\n", + "additionalProperties": { + "type": "object", + "description": "`{user_email}`: Object containing the details of a user's presence.\nThe object's key is the user's Zulip API email.\n", + "additionalProperties": { + "$ref": "#/components/schemas/LegacyPresenceFormat" + } + } + } + }, + "example": { + "msg": "", + "presences": { + "iago@zulip.com": { + "website": { + "client": "website", + "pushable": false, + "status": "active", + "timestamp": 1656958485 + }, + "aggregated": { + "client": "website", + "status": "active", + "timestamp": 1656958485 + } + } + }, + "result": "success", + "server_timestamp": 1656958539.6287155 + } + } + ] + } + } + } + } + } + } + }, + "/realm/profile_fields": { + "get": { + "operationId": "get-custom-profile-fields", + "summary": "Get all custom profile fields", + "tags": ["server_and_organizations"], + "description": "Get all the [custom profile fields](/help/custom-profile-fields)\nconfigured for the user's organization.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "custom_fields": { + "type": "array", + "description": "An array containing all the custom profile fields defined in this\nZulip organization.\n", + "items": { + "$ref": "#/components/schemas/CustomProfileField" + } + } + }, + "example": { + "result": "success", + "msg": "", + "custom_fields": [ + { + "id": 1, + "name": "Phone number", + "type": 1, + "hint": "", + "field_data": "", + "order": 1, + "required": true, + "editable_by_user": false + }, + { + "id": 2, + "name": "Biography", + "type": 2, + "hint": "What are you known for?", + "field_data": "", + "order": 2, + "required": true, + "editable_by_user": true + }, + { + "id": 3, + "name": "Favorite food", + "type": 1, + "hint": "Or drink, if you'd prefer", + "field_data": "", + "order": 3, + "required": false, + "editable_by_user": true + }, + { + "id": 4, + "name": "Favorite editor", + "type": 3, + "hint": "", + "field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}", + "order": 4, + "display_in_profile_summary": true, + "required": true, + "editable_by_user": true + }, + { + "id": 5, + "name": "Birthday", + "type": 4, + "hint": "", + "field_data": "", + "order": 5, + "required": false, + "editable_by_user": false + }, + { + "id": 6, + "name": "Favorite website", + "type": 5, + "hint": "Or your personal blog's URL", + "field_data": "", + "order": 6, + "display_in_profile_summary": true, + "required": false, + "editable_by_user": true + }, + { + "id": 7, + "name": "Mentor", + "type": 6, + "hint": "", + "field_data": "", + "order": 7, + "required": true, + "editable_by_user": false + }, + { + "id": 8, + "name": "GitHub", + "type": 7, + "hint": "Enter your GitHub username", + "field_data": "{\"subtype\":\"github\"}", + "order": 8, + "required": true, + "editable_by_user": true + }, + { + "id": 9, + "name": "Pronouns", + "type": 8, + "hint": "What pronouns should people use to refer to you?", + "order": 9, + "required": false, + "editable_by_user": true + } + ] + } + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "reorder-custom-profile-fields", + "summary": "Reorder custom profile fields", + "tags": ["server_and_organizations"], + "description": "Reorder the custom profile fields in the user's organization.\n\nCustom profile fields are displayed in Zulip UI widgets in order; this\nendpoint allows administrative settings UI to change the field ordering.\n\nThis endpoint is used to implement the dragging feature described in the\n[custom profile fields documentation](/help/custom-profile-fields).\n", + "x-requires-administrator": true, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "order": { + "description": "A list of the IDs of all the custom profile fields defined in this\norganization, in the desired new order.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1] + } + }, + "required": ["order"] + }, + "encoding": { + "order": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + }, + "post": { + "operationId": "create-custom-profile-field", + "summary": "Create a custom profile field", + "tags": ["server_and_organizations"], + "description": "[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.\n", + "x-requires-administrator": true, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the custom profile field, which will appear both in\nuser-facing settings UI for configuring custom profile fields and\nin UI displaying a user's profile.\n", + "type": "string", + "example": "Favorite programming language" + }, + "hint": { + "description": "The help text to be displayed for the custom profile field in user-facing\nsettings UI for configuring custom profile fields.\n", + "type": "string", + "example": "Your favorite programming language." + }, + "field_type": { + "description": "The field type can be any of the supported custom profile field types. See the\n[custom profile fields documentation](/help/custom-profile-fields)\nfor more details on what each type means.\n\n- **1**: Short text\n- **2**: Long text\n- **3**: List of options\n- **4**: Date picker\n- **5**: Link\n- **6**: Person picker\n- **7**: External account\n- **8**: Pronouns\n\n**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).\n", + "type": "integer", + "example": 3 + }, + "field_data": { + "description": "Field types 3 (List of options) and 7 (External account) support storing\nadditional configuration for the field type in the `field_data` attribute.\n\nFor field type 3 (List of options), this attribute is a JSON dictionary\ndefining the choices and the order they will be displayed in the\ndropdown UI for individual users to select an option.\n\nThe interface for field type 7 is not yet stabilized.\n", + "type": "object", + "example": { + "python": { + "text": "Python", + "order": "1" + }, + "java": { + "text": "Java", + "order": "2" + } + } + }, + "display_in_profile_summary": { + "description": "Whether clients should display this profile field in a summary section of a\nuser's profile (or in a more easily accessible \"small profile\").\n\nAt most 2 profile fields may have this property be true in a given\norganization. The \"Long text\" [profile field types][profile-field-types]\nprofile field types cannot be selected to be displayed in profile summaries.\n\nThe \"Person picker\" profile field is also not supported, but that is likely to\nbe temporary.\n\n[profile-field-types]: /help/custom-profile-fields#profile-field-types\n\n**Changes**: New in Zulip 6.0 (feature level 146).\n", + "type": "boolean", + "example": true + }, + "required": { + "description": "Whether an organization administrator has configured this profile field as\nrequired.\n\nBecause the required property is mutable, clients cannot assume that a required\ncustom profile field has a value. The Zulip web application displays a prominent\nbanner to any user who has not set a value for a required field.\n\n**Changes**: New in Zulip 9.0 (feature level 244).\n", + "type": "boolean", + "example": true + }, + "editable_by_user": { + "description": "Whether regular users can edit this profile field on their own account.\n\nNote that organization administrators can edit custom profile fields for any user\nregardless of this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 296).\n", + "type": "boolean", + "example": true + } + }, + "required": ["field_type"] + }, + "encoding": { + "field_type": { + "contentType": "application/json" + }, + "field_data": { + "contentType": "application/json" + }, + "display_in_profile_summary": { + "contentType": "application/json" + }, + "required": { + "contentType": "application/json" + }, + "editable_by_user": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The ID for the custom profile field.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "id": 9 + } + } + ] + } + } + } + } + } + } + }, + "/realm/user_settings_defaults": { + "patch": { + "operationId": "update-realm-user-settings-defaults", + "summary": "Update realm-level defaults of user settings", + "tags": ["server_and_organizations"], + "x-requires-administrator": true, + "description": "Change the [default values of settings][new-user-defaults] for new users\njoining the organization. Essentially all\n[personal preference settings](/api/update-settings) are supported.\n\nThis feature can be invaluable for customizing Zulip's default\nsettings for notifications or UI to be appropriate for how the\norganization is using Zulip. (Note that this only supports\npersonal preference settings, like when to send push\nnotifications or what emoji set to use, not profile or\nidentity settings that naturally should be different for each user).\n\nNote that this endpoint cannot, at present, be used to modify\nsettings for existing users in any way.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364)\nas we now have `web_font_size_px` and `web_line_height_percent`\nsettings for more control.\n\nNew in Zulip 5.0 (feature level 96). If any parameters sent in the\nrequest are not supported by this endpoint, an\n[`ignored_parameters_unsupported`][ignored-parameters] array will\nbe returned in the JSON success response.\n\n[new-user-defaults]: /help/configure-default-new-user-settings\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["left_side_userlist", "emojiset"] + } + } + ] + }, + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "starred_message_counts": { + "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n", + "type": "boolean", + "example": true + }, + "receives_typing_notifications": { + "description": "Whether the user is configured to receive typing notifications from other users.\nThe server will only deliver typing notifications events to users who for whom this\nis enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n", + "type": "boolean", + "example": true + }, + "web_suggest_update_timezone": { + "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n", + "type": "boolean", + "example": true + }, + "fluid_layout_width": { + "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n", + "type": "boolean", + "example": true + }, + "high_contrast_mode": { + "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n", + "type": "boolean", + "example": true + }, + "web_mark_read_on_scroll_policy": { + "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "web_channel_default_view": { + "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "web_font_size_px": { + "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", + "type": "integer", + "example": 14 + }, + "web_line_height_percent": { + "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", + "type": "integer", + "example": 122 + }, + "color_scheme": { + "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "enable_drafts_synchronization": { + "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n", + "type": "boolean", + "example": true + }, + "translate_emoticons": { + "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n", + "type": "boolean", + "example": true + }, + "display_emoji_reaction_users": { + "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting users, rather than\na count, for messages with few total reactions. The ideal cutoff may depend on\nthe space available for displaying reactions; the official web application\ndisplays names when 3 or fewer total reactions are present with this setting\nenabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n", + "type": "boolean", + "example": false + }, + "web_home_view": { + "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n", + "type": "string", + "example": "all_messages" + }, + "web_escape_navigates_to_home_view": { + "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called\n`escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107).\n", + "type": "boolean", + "example": true + }, + "left_side_userlist": { + "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n", + "type": "boolean", + "example": true + }, + "emojiset": { + "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n- \"google-blob\" - Google blobs\n", + "type": "string", + "example": "google" + }, + "demote_inactive_streams": { + "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "user_list_style": { + "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "web_animate_image_previews": { + "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images\nalways used to play in the message feed by default. This setting controls this\nbehaviour.\n", + "type": "string", + "enum": ["always", "on_hover", "never"], + "example": "on_hover" + }, + "web_stream_unreads_count_display_policy": { + "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 2 + }, + "hide_ai_features": { + "type": "boolean", + "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + }, + "web_left_sidebar_show_channel_folders": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n", + "example": true + }, + "web_left_sidebar_unreads_count_summary": { + "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n", + "type": "boolean", + "example": true + }, + "enable_stream_desktop_notifications": { + "description": "Enable visual desktop notifications for channel messages.\n", + "type": "boolean", + "example": true + }, + "enable_stream_email_notifications": { + "description": "Enable email notifications for channel messages.\n", + "type": "boolean", + "example": true + }, + "enable_stream_push_notifications": { + "description": "Enable mobile notifications for channel messages.\n", + "type": "boolean", + "example": true + }, + "enable_stream_audible_notifications": { + "description": "Enable audible desktop notifications for channel messages.\n", + "type": "boolean", + "example": true + }, + "notification_sound": { + "description": "Notification sound name.\n", + "type": "string", + "example": "ding" + }, + "enable_desktop_notifications": { + "description": "Enable visual desktop notifications for direct messages and @-mentions.\n", + "type": "boolean", + "example": true + }, + "enable_sounds": { + "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_desktop_notifications": { + "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_email_notifications": { + "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_push_notifications": { + "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": false + }, + "enable_followed_topic_audible_notifications": { + "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": false + }, + "email_notifications_batching_period_seconds": { + "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n", + "type": "integer", + "example": 120 + }, + "enable_offline_email_notifications": { + "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n", + "type": "boolean", + "example": true + }, + "enable_offline_push_notifications": { + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n", + "type": "boolean", + "example": true + }, + "enable_online_push_notifications": { + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n", + "type": "boolean", + "example": true + }, + "enable_digest_emails": { + "description": "Enable digest emails when the user is away.\n", + "type": "boolean", + "example": true + }, + "message_content_in_email_notifications": { + "description": "Include the message's content in email notifications for new messages.\n", + "type": "boolean", + "example": true + }, + "pm_content_in_desktop_notifications": { + "description": "Include content of direct messages in desktop notifications.\n", + "type": "boolean", + "example": true + }, + "wildcard_mentions_notify": { + "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_wildcard_mentions_notify": { + "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "desktop_icon_count_display": { + "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed\ntopics` option, renumbering the options to insert it in order.\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "realm_name_in_email_notifications_policy": { + "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "automatically_follow_topics_policy": { + "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "automatically_follow_topics_where_mentioned": { + "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n", + "type": "boolean", + "example": true + }, + "resolved_topic_notice_auto_read_policy": { + "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n", + "type": "string", + "enum": ["always", "except_followed", "never"], + "example": "except_followed" + }, + "presence_enabled": { + "description": "Display the presence status to other users when online.\n", + "type": "boolean", + "example": true + }, + "enter_sends": { + "description": "Whether pressing Enter in the compose box sends a message\n(or saves a message edit).\n", + "type": "boolean", + "example": true + }, + "twenty_four_hour_time": { + "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\n**Changes**: New in Zulip 5.0 (feature level 99).\nPreviously, this default was edited using the\n`default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint.\n", + "type": "boolean", + "example": true + }, + "send_private_typing_notifications": { + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "send_stream_typing_notifications": { + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "send_read_receipts": { + "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "email_address_visibility": { + "description": "The [policy][permission-level] for [which other users][help-email-visibility]\nin this organization can see the user's real email address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n", + "type": "integer", + "enum": [1, 2, 3, 4, 5], + "example": 1 + }, + "web_navigate_to_sent_message": { + "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n", + "type": "boolean", + "example": true + } + } + }, + "encoding": { + "starred_message_counts": { + "contentType": "application/json" + }, + "receives_typing_notifications": { + "contentType": "application/json" + }, + "web_suggest_update_timezone": { + "contentType": "application/json" + }, + "fluid_layout_width": { + "contentType": "application/json" + }, + "high_contrast_mode": { + "contentType": "application/json" + }, + "web_mark_read_on_scroll_policy": { + "contentType": "application/json" + }, + "web_channel_default_view": { + "contentType": "application/json" + }, + "web_font_size_px": { + "contentType": "application/json" + }, + "web_line_height_percent": { + "contentType": "application/json" + }, + "color_scheme": { + "contentType": "application/json" + }, + "enable_drafts_synchronization": { + "contentType": "application/json" + }, + "translate_emoticons": { + "contentType": "application/json" + }, + "display_emoji_reaction_users": { + "contentType": "application/json" + }, + "web_escape_navigates_to_home_view": { + "contentType": "application/json" + }, + "left_side_userlist": { + "contentType": "application/json" + }, + "demote_inactive_streams": { + "contentType": "application/json" + }, + "user_list_style": { + "contentType": "application/json" + }, + "web_stream_unreads_count_display_policy": { + "contentType": "application/json" + }, + "hide_ai_features": { + "contentType": "application/json" + }, + "web_left_sidebar_show_channel_folders": { + "contentType": "application/json" + }, + "web_left_sidebar_unreads_count_summary": { + "contentType": "application/json" + }, + "enable_stream_desktop_notifications": { + "contentType": "application/json" + }, + "enable_stream_email_notifications": { + "contentType": "application/json" + }, + "enable_stream_push_notifications": { + "contentType": "application/json" + }, + "enable_stream_audible_notifications": { + "contentType": "application/json" + }, + "enable_desktop_notifications": { + "contentType": "application/json" + }, + "enable_sounds": { + "contentType": "application/json" + }, + "enable_followed_topic_desktop_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_email_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_push_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_audible_notifications": { + "contentType": "application/json" + }, + "email_notifications_batching_period_seconds": { + "contentType": "application/json" + }, + "enable_offline_email_notifications": { + "contentType": "application/json" + }, + "enable_offline_push_notifications": { + "contentType": "application/json" + }, + "enable_online_push_notifications": { + "contentType": "application/json" + }, + "enable_digest_emails": { + "contentType": "application/json" + }, + "message_content_in_email_notifications": { + "contentType": "application/json" + }, + "pm_content_in_desktop_notifications": { + "contentType": "application/json" + }, + "wildcard_mentions_notify": { + "contentType": "application/json" + }, + "enable_followed_topic_wildcard_mentions_notify": { + "contentType": "application/json" + }, + "desktop_icon_count_display": { + "contentType": "application/json" + }, + "realm_name_in_email_notifications_policy": { + "contentType": "application/json" + }, + "automatically_follow_topics_policy": { + "contentType": "application/json" + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "contentType": "application/json" + }, + "automatically_follow_topics_where_mentioned": { + "contentType": "application/json" + }, + "presence_enabled": { + "contentType": "application/json" + }, + "enter_sends": { + "contentType": "application/json" + }, + "twenty_four_hour_time": { + "contentType": "application/json" + }, + "send_private_typing_notifications": { + "contentType": "application/json" + }, + "send_stream_typing_notifications": { + "contentType": "application/json" + }, + "send_read_receipts": { + "contentType": "application/json" + }, + "email_address_visibility": { + "contentType": "application/json" + }, + "web_navigate_to_sent_message": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessIgnoredParameters" + } + } + } + }, + "/users/me/subscriptions/properties": { + "post": { + "operationId": "update-subscription-settings", + "summary": "Update subscription settings", + "tags": ["channels"], + "description": "This endpoint is used to update the user's personal settings for the\nchannels they are subscribed to, including muting, color, pinning, and\nper-channel notification settings.\n\n**Changes**: Prior to Zulip 5.0 (feature level 111), response\nobject included the `subscription_data` in the\nrequest. The endpoint now returns the more ergonomic\n[`ignored_parameters_unsupported`][ignored-parameters] array instead.\n\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "subscription_data": { + "description": "A list of objects that describe the changes that should be applied in\neach subscription. Each object represents a subscription, and must have\na `stream_id` key that identifies the channel, as well as the `property`\nbeing modified and its new `value`.\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "stream_id": { + "type": "integer", + "description": "The unique ID of a channel.\n" + }, + "property": { + "type": "string", + "enum": [ + "color", + "is_muted", + "in_home_view", + "pin_to_top", + "desktop_notifications", + "audible_notifications", + "push_notifications", + "email_notifications", + "wildcard_mentions_notify" + ], + "description": "One of the channel properties described below:\n\n- `\"color\"`: The hex value of the user's display color for the channel.\n\n- `\"is_muted\"`: Whether the channel is [muted](/help/mute-a-channel).
\n **Changes**: As of Zulip 6.0 (feature level 139), updating either\n `\"is_muted\"` or `\"in_home_view\"` generates two [subscription update\n events](/api/get-events#subscription-update), one for each property,\n that are sent to clients. Prior to this feature level, updating either\n property only generated a subscription update event for\n `\"in_home_view\"`.
\n Prior to Zulip 2.1.0, this feature was represented\n by the more confusingly named `\"in_home_view\"` (with the\n opposite value: `in_home_view=!is_muted`); for\n backwards-compatibility, modern Zulip still accepts that property.\n\n- `\"pin_to_top\"`: Whether to pin the channel at the top of the channel list.\n\n- `\"desktop_notifications\"`: Whether to show desktop notifications\n for all messages sent to the channel.\n\n- `\"audible_notifications\"`: Whether to play a sound\n notification for all messages sent to the channel.\n\n- `\"push_notifications\"`: Whether to trigger a mobile push\n notification for all messages sent to the channel.\n\n- `\"email_notifications\"`: Whether to trigger an email\n notification for all messages sent to the channel.\n\n- `\"wildcard_mentions_notify\"`: Whether wildcard mentions trigger\n notifications as though they were personal mentions in this channel.\n" + }, + "value": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string" + } + ], + "description": "The new value of the property being modified.\n\nIf the property is `\"color\"`, then `value` is a string\nrepresenting the hex value of the user's display\ncolor for the channel. For all other above properties,\n`value` is a boolean.\n" + } + }, + "required": ["stream_id", "property", "value"], + "example": { + "stream_id": 2, + "property": "is_muted", + "value": true + } + }, + "example": [ + { + "stream_id": 1, + "property": "pin_to_top", + "value": true + }, + { + "stream_id": 3, + "property": "color", + "value": "#f00f00" + } + ] + } + }, + "required": ["subscription_data"] + }, + "encoding": { + "subscription_data": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessIgnoredParameters" + } + } + } + }, + "/users/{email}": { + "get": { + "operationId": "get-user-by-email", + "summary": "Get a user by email", + "tags": ["users"], + "description": "Fetch details for a single user in the organization given a Zulip\nAPI email address.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by user ID](/api/get-user).\n\nFetching by user ID is generally recommended when possible,\nas a user might [change their email address](/help/change-your-email-address)\nor change their [email address visibility](/help/configure-email-visibility),\neither of which could change the client's ability to look them up by that\nemail address.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), the real email\naddress can be used in the `email` parameter and will fetch the target user's\ndata if and only if the target's email visibility setting permits the requester\nto see the email address.\nThe dummy email addresses of the form `user{id}@{realm.host}` still work, and\nwill now work for **all** users, via identifying them by the embedded user ID.\n\nNew in Zulip Server 4.0 (feature level 39).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": [""] + } + }, + { + "type": "exclude", + "parameters": { + "enum": [""] + }, + "description": "You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:\n" + } + ] + }, + "parameters": [ + { + "name": "email", + "in": "path", + "description": "The email address of the user to fetch. Two forms are supported:\n\n- The real email address of the user (`delivery_email`). The lookup will\n succeed if and only if the user exists and their email address visibility\n setting permits the client to see the email address.\n\n- The dummy Zulip API email address of the form `user{user_id}@{realm_host}`. This\n is identical to simply [getting user by ID](/api/get-user). If the server or\n realm change domains, the dummy email address used has to be adjustment to\n match the new realm domain. This is legacy behavior for\n backwards-compatibility, and will be removed in a future release.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), lookups by real email\naddress match the semantics of the target's email visibility setting and dummy\nemail addresses work for all users, independently of their email visibility\nsetting.\n\nPreviously, lookups were done only using the Zulip API email addresses.\n", + "schema": { + "type": "string" + }, + "example": "iago@zulip.com", + "required": true + }, + { + "$ref": "#/components/parameters/ClientGravatar" + }, + { + "$ref": "#/components/parameters/IncludeCustomProfileFields" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "user": { + "$ref": "#/components/schemas/User" + } + }, + "example": { + "msg": "", + "result": "success", + "user": { + "date_joined": "2019-10-20T07:50:53.729659+00:00", + "full_name": "King Hamlet", + "is_guest": false, + "profile_data": { + "4": { + "value": "0" + }, + "2": { + "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", + "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" + }, + "5": { + "value": "1900-01-01" + }, + "7": { + "value": "[11]" + }, + "6": { + "value": "https://blog.zulig.org" + }, + "1": { + "value": "+0-11-23-456-7890", + "rendered_value": "

+0-11-23-456-7890

" + }, + "8": { + "value": "zulipbot" + }, + "3": { + "rendered_value": "

Dark chocolate

", + "value": "Dark chocolate" + } + }, + "user_id": 10, + "is_bot": false, + "bot_type": null, + "timezone": "", + "is_admin": false, + "is_owner": false, + "role": 400, + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "is_active": true, + "email": "hamlet@zulip.com", + "delivery_email": null + } + } + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "update-user-by-email", + "summary": "Update a user by email", + "tags": ["users"], + "x-requires-administrator": true, + "description": "Administrative endpoint to update the details of another user in the organization by their email address.\nWorks the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their\nreal email address.\n\nThe requester needs to have permission to view the target user's real email address, subject to the\nuser's email address visibility setting. Otherwise, the dummy address of the format\n`user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{email}`.\n\n**Changes**: New in Zulip 10.0 (feature level 313).\n", + "parameters": [ + { + "name": "email", + "in": "path", + "required": true, + "description": "The email address of the user, specified following the same rules as\n[`GET /users/{email}`](/api/get-user-by-email).\n", + "schema": { + "type": "string" + }, + "example": "hamlet@zulip.com" + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/UpdateUser" + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Guests cannot be organization administrators", + "code": "BAD_REQUEST" + }, + "description": "A typical unsuccessful JSON response:\n" + } + ] + } + } + } + } + } + } + }, + "/users/{user_id}": { + "get": { + "operationId": "get-user", + "summary": "Get a user", + "tags": ["users"], + "description": "Fetch details for a single user in the organization.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by a user's Zulip API email](/api/get-user-by-email).\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": [""] + } + }, + { + "type": "exclude", + "parameters": { + "enum": [""] + }, + "description": "You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:\n" + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + }, + { + "$ref": "#/components/parameters/ClientGravatar" + }, + { + "$ref": "#/components/parameters/IncludeCustomProfileFields" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "user": { + "$ref": "#/components/schemas/User" + } + }, + "example": { + "msg": "", + "result": "success", + "user": { + "date_joined": "2019-10-20T07:50:53.729659+00:00", + "full_name": "King Hamlet", + "is_guest": false, + "profile_data": { + "4": { + "value": "0" + }, + "2": { + "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", + "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" + }, + "5": { + "value": "1900-01-01" + }, + "7": { + "value": "[11]" + }, + "6": { + "value": "https://blog.zulig.org" + }, + "1": { + "value": "+0-11-23-456-7890", + "rendered_value": "

+0-11-23-456-7890

" + }, + "8": { + "value": "zulipbot" + }, + "3": { + "rendered_value": "

Dark chocolate

", + "value": "Dark chocolate" + } + }, + "user_id": 10, + "is_bot": false, + "bot_type": null, + "timezone": "", + "is_admin": false, + "is_owner": false, + "role": 400, + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "is_active": true, + "email": "hamlet@zulip.com", + "delivery_email": null + } + } + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "update-user", + "summary": "Update a user", + "tags": ["users"], + "x-requires-administrator": true, + "description": "Administrative endpoint to update the details of another user in the organization.\n\nSupports everything an administrator can do to edit details of another\nuser's account, including editing full name,\n[role](/help/user-roles), and [custom profile\nfields](/help/custom-profile-fields).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/UpdateUser" + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Guests cannot be organization administrators", + "code": "BAD_REQUEST" + }, + "description": "A typical unsuccessful JSON response:\n" + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "deactivate-user", + "summary": "Deactivate a user", + "tags": ["users"], + "x-requires-administrator": true, + "description": "[Deactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "deactivation_notification_comment": { + "description": "If not `null`, requests that the deactivated user receive\na notification email about their account deactivation.\n\nIf not `\"\"`, encodes custom text written by the administrator\nto be included in the notification email.\n\n**Changes**: New in Zulip 5.0 (feature level 135).\n", + "type": "string", + "example": "Farewell!\n" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Cannot deactivate the only organization owner", + "result": "error" + }, + "description": "An example JSON error response when attempting to deactivate the only\norganization owner in an organization:\n" + } + ] + } + } + } + } + } + } + }, + "/realm/linkifiers": { + "get": { + "operationId": "get-linkifiers", + "summary": "Get linkifiers", + "tags": ["server_and_organizations"], + "description": "List all of an organization's configured\n[linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 54). On older versions,\na similar `GET /realm/filters` endpoint was available with each entry in\na `[pattern, url_format, id]` tuple format.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "linkifiers": { + "type": "array", + "description": "An ordered array of objects, where each object\ndescribes a linkifier.\n\nClients should always process linkifiers in the order given;\nthis is important if the realm has linkifiers with overlapping\npatterns. The order can be modified using [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "pattern": { + "type": "string", + "description": "The string regex pattern which represents the pattern that\nshould be linkified by this linkifier.\n" + }, + "url_template": { + "type": "string", + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant\nURL template to be used for linkifying matches.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the linkifier.\n" + } + } + } + } + }, + "example": { + "msg": "", + "linkifiers": [ + { + "pattern": "#(?P[0-9]+)", + "url_template": "https://github.com/zulip/zulip/issues/{id}", + "id": 1 + } + ], + "result": "success" + } + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "reorder-linkifiers", + "summary": "Reorder linkifiers", + "tags": ["server_and_organizations"], + "description": "Change the order that the regular expression patterns in the organization's\n[linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics.\nUseful when defining linkifiers with overlapping patterns.\n\n**Changes**: New in Zulip 8.0 (feature level 202). Before this feature level,\nlinkifiers were always processed in order by ID, which meant users would\nneed to delete and recreate them to reorder the list of linkifiers.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "ordered_linkifier_ids": { + "description": "A list of the IDs of all the linkifiers defined in this\norganization, in the desired new order.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [3, 2, 1, 5] + } + }, + "required": ["ordered_linkifier_ids"] + }, + "encoding": { + "ordered_linkifier_ids": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/realm/filters": { + "post": { + "operationId": "add-linkifier", + "summary": "Add a linkifier", + "tags": ["server_and_organizations"], + "description": "Configure [linkifiers](/help/add-a-custom-linkifier),\nregular expression patterns that are automatically linkified when they\nappear in messages and topics.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "pattern": { + "$ref": "#/components/schemas/LinkifierPattern" + }, + "url_template": { + "$ref": "#/components/schemas/LinkifierURLTemplate" + } + }, + "required": ["pattern", "url_template"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The numeric ID assigned to this filter.\n" + } + }, + "example": { + "id": 42, + "result": "success", + "msg": "" + } + } + ] + } + } + } + } + } + } + }, + "/realm/filters/{filter_id}": { + "delete": { + "operationId": "remove-linkifier", + "summary": "Remove a linkifier", + "tags": ["server_and_organizations"], + "description": "Remove [linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n", + "parameters": [ + { + "name": "filter_id", + "in": "path", + "description": "The ID of the linkifier that you want to remove.\n", + "schema": { + "type": "integer" + }, + "example": 43, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + }, + "patch": { + "operationId": "update-linkifier", + "summary": "Update a linkifier", + "tags": ["server_and_organizations"], + "description": "Update a [linkifier](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 57).\n", + "parameters": [ + { + "name": "filter_id", + "in": "path", + "description": "The ID of the linkifier that you want to update.\n", + "schema": { + "type": "integer" + }, + "example": 5, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "pattern": { + "$ref": "#/components/schemas/LinkifierPattern" + }, + "url_template": { + "$ref": "#/components/schemas/LinkifierURLTemplate" + } + }, + "required": ["pattern", "url_template"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/realm/playgrounds": { + "post": { + "operationId": "add-code-playground", + "summary": "Add a code playground", + "tags": ["server_and_organizations"], + "description": "Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was\nfixed in Zulip 4.0 (feature level 57).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The user-visible display name of the playground which can be\nused to pick the target playground, especially when multiple\nplayground options exist for that programming language.\n", + "type": "string", + "example": "Python playground" + }, + "pygments_language": { + "description": "The name of the Pygments language lexer for that\nprogramming language.\n", + "type": "string", + "example": "Python" + }, + "url_template": { + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template for the playground. The template should\ncontain exactly one variable named `code`, which determines how the\nextracted code should be substituted in the playground URL.\n\n**Changes**: New in Zulip 8.0 (feature level 196). This replaced the\n`url_prefix` parameter, which was used to construct URLs by just\nconcatenating `url_prefix` and `code`.\n", + "type": "string", + "example": "https://python.example.com?code={code}" + } + }, + "required": ["name", "pygments_language", "url_template"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The numeric ID assigned to this playground.\n" + } + }, + "example": { + "id": 1, + "result": "success", + "msg": "" + } + } + ] + } + } + } + } + } + } + }, + "/realm/playgrounds/{playground_id}": { + "delete": { + "operationId": "remove-code-playground", + "summary": "Remove a code playground", + "tags": ["server_and_organizations"], + "description": "Remove a [code playground](/help/code-blocks#code-playgrounds) previously\nconfigured for an organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n", + "parameters": [ + { + "name": "playground_id", + "in": "path", + "description": "The ID of the playground that you want to remove.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/export/realm": { + "get": { + "operationId": "get-realm-exports", + "summary": "Get all data exports", + "tags": ["server_and_organizations"], + "x-requires-administrator": true, + "description": "Fetch all the public and standard [data exports][export-data]\nof the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be fetched using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "exports": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains\ndetails about a data export of the organization.\n", + "items": { + "$ref": "#/components/schemas/RealmExport" + } + } + }, + "example": { + "exports": [ + { + "acting_user_id": 11, + "deleted_timestamp": null, + "export_type": 1, + "export_time": 1722243168.134179, + "export_url": "http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz", + "id": 323, + "failed_timestamp": null, + "pending": false + } + ], + "msg": "", + "result": "success" + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "export-realm", + "summary": "Create a data export", + "tags": ["server_and_organizations"], + "x-requires-administrator": true, + "description": "Create a public or a standard [data export][export-data] of the organization.\n\n!!! warn \"\"\n\n **Note**: If you're the administrator of a self-hosted installation,\n you may be looking for the documentation on [server data export and\n import][data-export] or [server backups][backups].\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be created using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server\n[data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export\n[backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "export_type": { + "description": "Whether to create a public or a standard data export.\n\n- 1 = Public data export.\n- 2 = Standard data export.\n\nIf not specified, defaults to 1.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nall export requests were public data exports.\n", + "type": "integer", + "enum": [1, 2], + "default": 1, + "example": 2 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The ID of the data export created.\n\n**Changes**: New in Zulip 7.0 (feature level 182).\n" + } + }, + "example": { + "id": 1, + "result": "success", + "msg": "" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Please request a manual export from zulip-admin@example.com.", + "result": "error" + }, + "description": "An example JSON error response for when the data export\nexceeds the maximum allowed data export size.\n" + } + ] + } + } + } + } + } + } + }, + "/export/realm/consents": { + "get": { + "operationId": "get-realm-export-consents", + "summary": "Get data export consent state", + "tags": ["server_and_organizations"], + "x-requires-administrator": true, + "description": "Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data)\nfor their private data to be exported by organization administrators.\n\n**Changes**: New in Zulip 10.0 (feature level 295).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "export_consents": { + "type": "array", + "description": "An array of objects where each object contains a user ID and\nwhether the user has consented for their private data to be exported.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "user_id": { + "description": "The user ID.\n", + "type": "integer" + }, + "consented": { + "description": "Whether the user has consented for their private data export.\n", + "type": "boolean" + } + } + } + } + }, + "example": { + "export_consents": [ + { + "user_id": 11, + "consented": true + }, + { + "user_id": 6, + "consented": false + } + ], + "msg": "", + "result": "success" + } + } + ] + } + } + } + } + } + } + }, + "/invites": { + "get": { + "operationId": "get-invites", + "summary": "Get all invitations", + "tags": ["invites"], + "description": "Fetch all unexpired [invitations](/help/invite-new-users) (i.e. email\ninvitations and reusable invitation links) that can be managed by the user.\n\nNote that administrators can manage invitations that were created by other users.\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), non-admin users could\nonly create email invitations, and therefore the response would never include\nreusable invitation links for these users.\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "invites": { + "type": "array", + "description": "An array of objects, each representing a single unexpired\n[invitation](/help/invite-new-users).\n", + "items": { + "$ref": "#/components/schemas/Invite" + } + } + }, + "example": { + "result": "success", + "msg": "", + "invites": [ + { + "email": "example@zulip.com", + "expiry_date": null, + "id": 1, + "invited": 1710606654, + "invited_as": 200, + "invited_by_user_id": 9, + "notify_referrer_on_join": true, + "is_multiuse": false + }, + { + "expiry_date": 1711463862, + "id": 1, + "invited": 1710599862, + "invited_as": 400, + "invited_by_user_id": 9, + "is_multiuse": true, + "notify_referrer_on_join": true, + "link_url": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/" + } + ] + } + } + ] + } + } + } + } + } + }, + "post": { + "operationId": "send-invites", + "summary": "Send invitations", + "tags": ["invites"], + "description": "Send [invitations](/help/invite-new-users) to specified email addresses.\n\n**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `invite_expires_in_minutes`.\n\nIn Zulip 5.0 (feature level 117), added support for passing `null` as\nthe `invite_expires_in_days` parameter to request an invitation that never\nexpires.\n\nIn Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was\nadded which specified the number of days before the invitation would expire.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "invitee_emails": { + "description": "The string containing the email addresses, separated by commas or\nnewlines, that will be sent an invitation.\n", + "type": "string", + "example": "example@zulip.com, logan@zulip.com" + }, + "invite_expires_in_minutes": { + "$ref": "#/components/schemas/InviteExpirationParameter" + }, + "invite_as": { + "$ref": "#/components/schemas/InviteRoleParameter" + }, + "stream_ids": { + "description": "A list containing the [IDs of the channels](/api/get-stream-id) that the\nnewly created user will be automatically subscribed to if the invitation\nis accepted, in addition to any default channels that the new user may\nbe subscribed to based on the `include_realm_default_subscriptions`\nparameter.\n\nRequested channels must either be default channels for the\norganization, or ones the acting user has permission to add\nsubscribers to.\n\nThis list must be empty if the current user has the unlikely\nconfiguration of being able to send invitations while lacking\npermission to [subscribe other users to channels][can-subscribe-others].\n\n**Changes**: Prior to Zulip 10.0 (feature level 342), default channels\nthat the acting user did not directly have permission to add\nsubscribers to would be rejected.\n\nBefore Zulip 7.0 (feature level 180), specifying `stream_ids` as an\nempty list resulted in an error.\n\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [1, 10] + }, + "group_ids": { + "description": "A list containing the [IDs of the user groups](/api/get-user-groups) that\nthe newly created user will be automatically added to if the invitation\nis accepted. If the list is empty, then the new user will not be\nadded to any user groups. The acting user must have permission to add users\nto the groups listed in this request.\n\n**Changes**: New in Zulip 10.0 (feature level 322).\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [] + }, + "include_realm_default_subscriptions": { + "description": "Boolean indicating whether the newly created user should be subscribed\nto the [default channels][default-channels] for the organization.\n\nNote that this parameter can be `true` even if the user creating the\ninvitation does not generally have permission to [subscribe other\nusers to channels][can-subscribe-others].\n\n**Changes**: New in Zulip 9.0 (feature level 261). Previous versions\nof Zulip behaved as though this parameter was always `false`; clients\nneeded to include the organization's default channels in the\n`stream_ids` parameter for a newly created user to be automatically\nsubscribed to them.\n\n[default-channels]: /help/set-default-channels-for-new-users\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", + "type": "boolean", + "default": false, + "example": false + }, + "notify_referrer_on_join": { + "description": "A boolean indicating whether the referrer would like to receive a\ndirect message from [notification\nbot](/help/configure-automated-notices) when a user account is created\nusing this invitation.\n\n**Changes**: New in Zulip 9.0 (feature level 267). Previously,\nreferrers always received such direct messages.\n", + "type": "boolean", + "example": false, + "default": true + }, + "welcome_message_custom_text": { + "description": "Custom message text, in Zulip Markdown format, to be sent by the\nWelcome Bot to new users that join the organization via this\ninvitation.\n\nMaximum length is 8000 characters.\n\nOnly organization administrators can use this feature; for other\nusers, the value is always `null`.\n\n- `null`: the organization's default `welcome_message_custom_text` is used.\n- Empty string: no Welcome Bot custom message is sent.\n- Otherwise, the provided string is the custom message.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", + "type": "string", + "nullable": true, + "example": "Welcome to Zulip! We're excited to have you on board." + } + }, + "required": ["invitee_emails", "stream_ids"] + }, + "encoding": { + "invite_expires_in_minutes": { + "contentType": "application/json" + }, + "stream_ids": { + "contentType": "application/json" + }, + "group_ids": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {} + }, + "example": { + "msg": "", + "result": "success" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/InvitationFailedError" + }, + { + "example": { + "result": "error", + "msg": "Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!", + "errors": [ + [ + "hamlet@zulip.com", + "Already has an account.", + false + ] + ], + "sent_invitations": true, + "license_limit_reached": false, + "daily_limit_reached": false, + "code": "INVITATION_FAILED" + }, + "description": "An example JSON error response for when some of the specified email addresses\nhave existing Zulip accounts.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Insufficient permission", + "result": "error" + }, + "description": "An example JSON error response for when the user doesn't have permission\nto send invitations.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "You must specify at least one email address.", + "result": "error" + }, + "description": "An example JSON error response for when no email address is specified.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid channel ID 11. No invites were sent.", + "result": "error" + }, + "description": "An example JSON error response for when any of the specified channels\ndoes not exist or the user does not have permission to access one of\nthe targeted channels.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "You do not have permission to subscribe other users to channels.", + "result": "error" + }, + "description": "An example JSON error response for when the user doesn't have permission\nto subscribe other users to channels and `stream_ids` is not empty.\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/invites/multiuse": { + "post": { + "operationId": "create-invite-link", + "summary": "Create a reusable invitation link", + "tags": ["invites"], + "description": "Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)\nwhich can be used to invite new users to the organization.\n\n**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin\nusers [with permission](/help/restrict-account-creation#change-who-can-send-invitations)\nto use this endpoint. Previously, it was restricted to administrators only.\n\nIn Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `invite_expires_in_minutes`.\n\nIn Zulip 5.0 (feature level 117), added support for passing `null` as\nthe `invite_expires_in_days` parameter to request an invitation that never\nexpires.\n\nIn Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was\nadded which specified the number of days before the invitation would expire.\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "invite_expires_in_minutes": { + "$ref": "#/components/schemas/InviteExpirationParameter" + }, + "invite_as": { + "$ref": "#/components/schemas/InviteRoleParameter" + }, + "stream_ids": { + "description": "A list containing the [IDs of the channels](/api/get-stream-id) that the\nnewly created user will be automatically subscribed to if the invitation\nis accepted, in addition to any default channels that the new user may\nbe subscribed to based on the `include_realm_default_subscriptions`\nparameter.\n\nRequested channels must either be default channels for the\norganization, or ones the acting user has permission to add\nsubscribers to.\n\nThis list must be empty if the current user has the unlikely\nconfiguration of being able to create reusable invitation links while\nlacking permission to [subscribe other users to\nchannels][can-subscribe-others].\n\n**Changes**: Prior to Zulip 10.0 (feature level 342), default channels\nthat the acting user did not directly have permission to add\nsubscribers to would be rejected.\n\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", + "type": "array", + "items": { + "type": "integer" + }, + "default": [], + "example": [1, 10] + }, + "group_ids": { + "description": "A list containing the [IDs of the user groups](/api/get-user-groups) that\nthe newly created user will be automatically added to if the invitation\nis accepted. If the list is empty, then the new user will not be\nadded to any user groups. The acting user must have permission to add users\nto the groups listed in this request.\n\n**Changes**: New in Zulip 10.0 (feature level 322).\n", + "type": "array", + "items": { + "type": "integer" + }, + "default": [], + "example": [] + }, + "include_realm_default_subscriptions": { + "description": "Boolean indicating whether the newly created user should be subscribed\nto the [default channels][default-channels] for the organization.\n\nNote that this parameter can be `true` even if the current user does\nnot generally have permission to [subscribe other users to\nchannels][can-subscribe-others].\n\n**Changes**: New in Zulip 9.0 (feature level 261). Previous versions\nof Zulip behaved as though this parameter was always `false`; clients\nneeded to include the organization's default channels in the\n`stream_ids` parameter for a newly created user to be automatically\nsubscribed to them.\n\n[default-channels]: /help/set-default-channels-for-new-users\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", + "type": "boolean", + "default": false, + "example": false + }, + "welcome_message_custom_text": { + "description": "Custom message text, in Zulip Markdown format, to be sent by the\nWelcome Bot to new users that join the organization via this\ninvitation.\n\nMaximum length is 8000 characters.\n\nOnly organization administrators can use this feature; for other\nusers, the value is always `null`.\n\n- `null`: the organization's default `welcome_message_custom_text` is used.\n- Empty string: no Welcome Bot custom message is sent.\n- Otherwise, the provided string is the custom message.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", + "type": "string", + "nullable": true, + "example": "Welcome to Zulip! We're excited to have you on board." + } + } + }, + "encoding": { + "invite_expires_in_minutes": { + "contentType": "application/json" + }, + "stream_ids": { + "contentType": "application/json" + }, + "group_ids": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "invite_link": { + "type": "string", + "description": "The URL of the [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)\nthat was created by this request.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "invite_link": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Insufficient permission", + "result": "error" + }, + "description": "An example JSON error response for when the user doesn't have permission\nto send invitations.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid channel ID 11. No invites were sent.", + "result": "error" + }, + "description": "An example JSON error response for when any of the specified channels\ndoes not exist or the user does not have permission to access one of\nthe targeted channels.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "You do not have permission to subscribe other users to channels.", + "result": "error" + }, + "description": "An example JSON error response for when the user doesn't have permission\nto subscribe other users to channels and `stream_ids` is not empty.\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/invites/{invite_id}": { + "delete": { + "operationId": "revoke-email-invite", + "summary": "Revoke an email invitation", + "tags": ["invites"], + "description": "Revoke an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n", + "parameters": [ + { + "name": "invite_id", + "in": "path", + "description": "The ID of the email invitation to be revoked.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "No such invitation", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for an invalid email invitation ID:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/invites/multiuse/{invite_id}": { + "delete": { + "operationId": "revoke-invite-link", + "summary": "Revoke a reusable invitation link", + "tags": ["invites"], + "description": "Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), only organization\nadministrators were able to create and revoke reusable invitation links.\n", + "parameters": [ + { + "name": "invite_id", + "in": "path", + "description": "The ID of the reusable invitation link to be revoked.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "No such invitation", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for an invalid invitation link ID:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Invitation has already been revoked", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for when the invitation link has already\nbeen revoked:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/invites/{invite_id}/resend": { + "post": { + "operationId": "resend-email-invite", + "summary": "Resend an email invitation", + "tags": ["invites"], + "description": "Resend an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only resend [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n", + "parameters": [ + { + "name": "invite_id", + "in": "path", + "description": "The ID of the email invitation to be resent.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "No such invitation", + "code": "BAD_REQUEST" + }, + "description": "A typical failed JSON response for an invalid email invitation ID:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/realm/test_welcome_bot_custom_message": { + "post": { + "operationId": "test-welcome-bot-custom-message", + "summary": "Test welcome bot custom message", + "tags": ["server_and_organizations"], + "x-requires-administrator": true, + "description": "Sends a test Welcome Bot custom message to the acting administrator.\nThis allows administrators to preview how the custom welcome message will\nappear when received by new users upon joining the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "welcome_message_custom_text": { + "description": "Custom message text, in Zulip Markdown format, to be used for\nthis test message.\n\nMaximum length is 8000 characters.\n", + "type": "string", + "maxLength": 8000, + "example": "Welcome to Zulip! We're excited to have you on board." + } + }, + "required": ["welcome_message_custom_text"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "message_id": { + "type": "integer", + "description": "The message_id of the test welcome bot custom message.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "message_id": 1 + } + } + ] + } + } + } + } + } + } + }, + "/register": { + "post": { + "operationId": "register-queue", + "summary": "Register an event queue", + "tags": ["real_time_events"], + "description": "This powerful endpoint can be used to register a Zulip \"event queue\"\n(subscribed to certain types of \"events\", or updates to the messages\nand other Zulip data the current user has access to), as well as to\nfetch the current state of that data.\n\n(`register` also powers the `call_on_each_event` Python API, and is\nintended primarily for complex applications for which the more convenient\n`call_on_each_event` API is insufficient).\n\nThis endpoint returns a `queue_id` and a `last_event_id`; these can be\nused in subsequent calls to the\n[\"events\" endpoint](/api/get-events) to request events from\nthe Zulip server using long-polling.\n\nThe server will queue events for up to 10 minutes of inactivity.\nAfter 10 minutes, your event queue will be garbage-collected. The\nserver will send `heartbeat` events every minute, which makes it easy\nto implement a robust client that does not miss events unless the\nclient loses network connectivity with the Zulip server for 10 minutes\nor longer.\n\nOnce the server garbage-collects your event queue, the server will\n[return an error](/api/get-events#bad_event_queue_id-errors)\nwith a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from\nthe event queue. Your software will need to handle that error\ncondition by re-initializing itself (e.g. this is what triggers your\nbrowser reloading the Zulip web app when your laptop comes back online\nafter being offline for more than 10 minutes).\n\nWhen prototyping with this API, we recommend first calling `register`\nwith no `event_types` parameter to see all the available data from all\nsupported event types. Before using your client in production, you\nshould set appropriate `event_types` and `fetch_event_types` filters\nso that your client only requests the data it needs. A few minutes\ndoing this often saves 90% of the total bandwidth and other resources\nconsumed by a client using this API.\n\nSee the [events system developer documentation][events-system-docs]\nif you need deeper details about how the Zulip event queue system\nworks, avoids clients needing to worry about large classes of\npotentially messy races, etc.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364)\nas we now have `web_font_size_px` and `web_line_height_percent`\nsettings for more control.\n\nBefore Zulip 7.0 (feature level 183), the\n`realm_community_topic_editing_limit_seconds` property\nwas returned by the response. It was removed because it\nhad not been in use since the realm setting\n`move_messages_within_stream_limit_seconds` was introduced\nin feature level 162.\n\nIn Zulip 7.0 (feature level 163), the realm setting\n`email_address_visibility` was removed. It was replaced by a [user\nsetting](/api/update-settings#parameter-email_address_visibility) with\na [realm user default][user-defaults], with the encoding of different\nvalues preserved. Clients can support all versions by supporting the\ncurrent API and treating every user as having the realm's\n`email_address_visibility` value.\n\n[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility\n[events-system-docs]: https://zulip.readthedocs.io/en/latest/subsystems/events-system.html\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["event_types"] + } + } + ] + }, + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "apply_markdown": { + "description": "Set to `true` if you would like the content to be rendered in HTML\nformat (otherwise the API will return the raw text that the user\nentered)\n", + "type": "boolean", + "default": false, + "example": true + }, + "client_gravatar": { + "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\nThe default value is `true` for authenticated requests and\n`false` for [unauthenticated\nrequests](/help/public-access-option). Passing `true` in\nan unauthenticated request is an error.\n\n**Changes**: Before Zulip 6.0 (feature level 149), this\nparameter was silently ignored and processed as though it\nwere `false` in unauthenticated requests.\n", + "type": "boolean", + "example": false + }, + "include_subscribers": { + "description": "Whether each returned channel object should include a `subscribers`\nfield containing a list of the user IDs of its subscribers.\n\nClient apps supporting organizations with many thousands of users\nshould not pass `true`, because the full subscriber matrix may be\nseveral megabytes of data. The `partial` value, combined with the\n`subscriber_count` and fetching subscribers for individual channels as\nneeded, is recommended to support client app features where channel\nsubscriber data is useful.\n\nIf a client passes `partial` for this parameter, the server may,\nfor some channels, return a subset of the channel's subscribers\nin the `partial_subscribers` field instead of the `subscribers` field,\nwhich always contains the complete set of subscribers.\n\nThe server guarantees that it will always return a `subscribers`\nfield for channels with fewer than 250 total subscribers. When\nreturning a `partial_subscribers` field, the server guarantees\nthat all bot users and users active within the last 14 days will\nbe included. For other cases, the server may use its discretion\nto determine which channels and users to include, balancing between\npayload size and usefulness of the data provided to the client.\n\nPassing `true` in an [unauthenticated\nrequest](/help/public-access-option) is an error.\n\n**Changes**: The `partial` value is new in Zulip 11.0 (feature level 412).\n\nBefore Zulip 6.0 (feature level 149), this parameter was silently\nignored and processed as though it were `false` in unauthenticated\nrequests.\n\nNew in Zulip 2.1.0.\n", + "type": "string", + "enum": ["true", "false", "partial"], + "default": "false", + "example": "true" + }, + "slim_presence": { + "description": "If `true`, the `presences` object returned in the response will be keyed\nby user ID and the entry for each user's presence data will be in the\nmodern format.\n\n**Changes**: New in Zulip 3.0 (no feature level; API unstable).\n", + "type": "boolean", + "default": false, + "example": true + }, + "presence_history_limit_days": { + "description": "Limits how far back in time to fetch user presence data. If not specified,\ndefaults to 14 days. A value of N means that the oldest presence data\nfetched will be from at most N days ago.\n\n**Changes**: New in Zulip 10.0 (feature level 288).\n", + "type": "integer", + "example": 365 + }, + "event_types": { + "$ref": "#/components/schemas/Event_types" + }, + "all_public_streams": { + "$ref": "#/components/schemas/AllPublicChannels" + }, + "client_capabilities": { + "description": "Dictionary containing details on features the client supports that are\nrelevant to the format of responses sent by the server.\n\n- `notification_settings_null`: Boolean for whether the\n client can handle the current API with `null` values for\n channel-level notification settings (which means the channel\n is not customized and should inherit the user's global\n notification settings for channel messages).\n
\n **Changes**: New in Zulip 2.1.0. In earlier Zulip releases,\n channel-level notification settings were simple booleans.\n\n- `bulk_message_deletion`: Boolean for whether the client's\n handler for the `delete_message` event type has been\n updated to process the new bulk format (with a\n `message_ids`, rather than a singleton `message_id`).\n Otherwise, the server will send `delete_message` events\n in a loop.\n
\n **Changes**: New in Zulip 3.0 (feature level 13). This\n capability is for backwards-compatibility; it will be\n required in a future server release.\n\n- `user_avatar_url_field_optional`: Boolean for whether the\n client required avatar URLs for all users, or supports\n using `GET /avatar/{user_id}` to access user avatars. If the\n client has this capability, the server may skip sending a\n `avatar_url` field in the `realm_user` at its sole discretion\n to optimize network performance. This is an important optimization\n in organizations with 10,000s of users.\n
\n **Changes**: New in Zulip 3.0 (feature level 18).\n\n- `stream_typing_notifications`: Boolean for whether the client\n supports channel typing notifications.\n
\n **Changes**: New in Zulip 4.0 (feature level 58). This capability is\n for backwards-compatibility; it will be required in a\n future server release.\n\n- `user_settings_object`: Boolean for whether the client supports the modern\n `user_settings` event type. If false, the server will additionally send the\n legacy `update_global_notifications` and `update_display_settings` event\n types.\n
\n **Changes**: New in Zulip 5.0 (feature level 89). This capability is for\n backwards-compatibility; it will be removed in a future server release.\n Because the feature level 89 API changes were merged together, clients can\n safely make a request with this client capability and also request all three\n event types (`user_settings`, `update_display_settings`,\n `update_global_notifications`), and get exactly one copy of settings data on\n any server version. Clients can then use the `zulip_feature_level` in the\n `/register` response or the presence/absence of a `user_settings` key to\n determine where to look for the data.\n\n- `linkifier_url_template`: Boolean for whether the client accepts\n [linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant\n URL templates for linkifying matches. If false or unset, then the\n `realm_linkifiers` array in the `/register` response will be empty\n if present, and no `realm_linkifiers` [events][events-linkifiers]\n will be sent to the client.\n
\n **Changes**: New in Zulip 7.0 (feature level 176). This capability\n is for backwards-compatibility.\n\n- `user_list_incomplete`: Boolean for whether the client supports not having an\n incomplete user database. If true, then the `realm_users` array in the `register`\n response will not include data for inaccessible users and clients of guest users will\n not receive `realm_user op:add` events for newly created users that are not accessible\n to the current user.\n
\n **Changes**: New in Zulip 8.0 (feature level 232). This\n capability is for backwards-compatibility.\n\n- `include_deactivated_groups`: Boolean for whether the client can handle\n deactivated user groups by themselves. If false, then the `realm_user_groups`\n array in the `/register` response will only include active groups, clients\n will receive a `remove` event instead of `update` event when a group is\n deactivated and no `update` event will be sent to the client if a deactivated\n user group is renamed.\n
\n **Changes**: New in Zulip 10.0 (feature level 294). This\n capability is for backwards-compatibility.\n\n- `archived_channels`: Boolean for whether the client supports processing\n [archived channels](/help/archive-a-channel) in the `stream` and\n `subscription` event types. If `false`, the server will not include data\n related to archived channels in the `register` response or in events.\n
\n **Changes**: New in Zulip 10.0 (feature level 315). This allows clients to\n access archived channels, without breaking backwards-compatibility for\n existing clients.\n\n- `empty_topic_name`: Boolean for whether the client supports processing\n the empty string as a topic name. Clients not declaring this capability\n will be sent the value of `realm_empty_topic_display_name` found in the\n [POST /register](/api/register-queue) response instead of the empty string\n wherever topic names appear in the register response or events involving\n topic names.\n
\n **Changes**: New in Zulip 10.0 (feature level 334). Previously,\n the empty string was not a valid topic name.\n\n- `simplified_presence_events`: Boolean for whether the client supports\n receiving the [`presence` event type](/api/get-events#presence) with\n user presence data in the modern format. If true, the server will\n send these events with the `presences` field that has the user presence\n data in the modern format. Otherwise, these event will contain fields\n with legacy format user presence data.\n
\n **Changes**: New in Zulip 11.0 (feature level 419).\n\n[help-linkifiers]: /help/add-a-custom-linkifier\n[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html\n[events-linkifiers]: /api/get-events#realm_linkifiers\n", + "type": "object", + "example": { + "notification_settings_null": true + } + }, + "fetch_event_types": { + "description": "Same as the `event_types` parameter except that the values in\n`fetch_event_types` are used to fetch initial data. If\n`fetch_event_types` is not provided, `event_types` is used and if\n`event_types` is not provided, this parameter defaults to `null`.\n\nEvent types not supported by the server are ignored, in order to simplify\nthe implementation of client apps that support multiple server versions.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["message"] + }, + "narrow": { + "$ref": "#/components/schemas/Narrow" + } + } + }, + "encoding": { + "apply_markdown": { + "contentType": "application/json" + }, + "client_gravatar": { + "contentType": "application/json" + }, + "slim_presence": { + "contentType": "application/json" + }, + "event_types": { + "contentType": "application/json" + }, + "all_public_streams": { + "contentType": "application/json" + }, + "client_capabilities": { + "contentType": "application/json" + }, + "fetch_event_types": { + "contentType": "application/json" + }, + "narrow": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "queue_id": { + "type": "string", + "nullable": true, + "description": "The ID of the queue that has been allocated for your client.\n\nWill be `null` only for unauthenticated access in realms that have\nenabled the [public access option](/help/public-access-option).\n" + }, + "last_event_id": { + "type": "integer", + "description": "The initial value of `last_event_id` to pass to `GET /api/v1/events`.\n" + }, + "zulip_feature_level": { + "type": "integer", + "description": "The server's current [Zulip feature level](/api/changelog).\n\n**Changes**: As of Zulip 3.0 (feature level 3), this is always present\nin the endpoint's response. Previously, it was only present if\n`event_types` included `zulip_version`.\n\nNew in Zulip 3.0 (feature level 1).\n" + }, + "zulip_version": { + "type": "string", + "description": "The server's version number. This is often a release version number,\nlike `2.1.7`. But for a server running a [version from Git][git-release],\nit will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.\n\n**Changes**: As of Zulip 3.0 (feature level 3), this is always present\nin the endpoint's response. Previously, it was only present if\n`event_types` included `zulip_version`.\n\n[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions\n" + }, + "zulip_merge_base": { + "type": "string", + "description": "The `git merge-base` between `zulip_version` and official branches\nin the public\n[Zulip server and web app repository](https://github.com/zulip/zulip),\nin the same format as `zulip_version`. This will equal\n`zulip_version` if the server is not running a fork of the Zulip server.\n\nThis will be `\"\"` if the server does not know its `merge-base`.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" + }, + "alert_words": { + "type": "array", + "description": "Present if `alert_words` is present in `fetch_event_types`.\n\nAn array of strings, each an [alert word](/help/dm-mention-alert-notifications#alert-words)\nthat the current user has configured.\n", + "items": { + "type": "string" + } + }, + "custom_profile_fields": { + "type": "array", + "description": "Present if `custom_profile_fields` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary contains the\ndetails of a single custom profile field that is available to users\nin this Zulip organization. This must be combined with the custom profile\nfield values on individual user objects to display users' profiles.\n", + "items": { + "$ref": "#/components/schemas/CustomProfileField" + } + }, + "custom_profile_field_types": { + "type": "object", + "description": "Present if `custom_profile_fields` is present in `fetch_event_types`.\n\nAn array of objects; each object describes a type of custom profile field\nthat could be configured on this Zulip server. Each custom profile type\nhas an ID and the `type` property of a custom profile field is equal\nto one of these IDs.\n\nThis attribute is only useful for clients containing UI for changing\nthe set of configured custom profile fields in a Zulip organization.\n", + "additionalProperties": { + "type": "object", + "description": "`{FIELD_TYPE}`: Dictionary which contains the details\nof the field type with the field type as the name of the\nproperty itself. The current supported field types are as follows:\n\n- `SHORT_TEXT`\n- `LONG_TEXT`\n- `DATE` for date-based fields.\n- `SELECT` for a list of options.\n- `URL` for links.\n- `EXTERNAL_ACCOUNT` for external accounts.\n- `USER` for selecting a user for the field.\n- `PRONOUNS` for a short text field with convenient typeahead for one's preferred pronouns.\n\n**Changes**: `PRONOUNS` type added in Zulip 6.0 (feature level 151).\n", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "The ID of the custom profile field type.\n" + }, + "name": { + "type": "string", + "description": "The name of the custom profile field type.\n" + } + } + } + }, + "realm_date_created": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe UNIX timestamp (UTC) for when the organization was\ncreated.\n\n**Changes**: New in Zulip 8.0 (feature level 203).\n" + }, + "demo_organization_scheduled_deletion_date": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`,\nand the realm is a demo organization.\n\nThe UNIX timestamp (UTC) when the demo organization will be\nautomatically deleted. Clients should use this to display a\nprominent warning to the user that the organization will be\ndeleted at the indicated time.\n\n**Changes**: New in Zulip 5.0 (feature level 94).\n" + }, + "drafts": { + "type": "array", + "description": "An array containing draft objects for the user. These drafts are being\nstored on the backend for the purpose of syncing across devices. This\narray will be empty if `enable_drafts_synchronization` is set to `false`.\n", + "items": { + "$ref": "#/components/schemas/Draft" + } + }, + "onboarding_steps": { + "type": "array", + "description": "Present if `onboarding_steps` is present in `fetch_event_types`.\n\nAn array of dictionaries, where each dictionary contains details about\na single onboarding step that should be shown to the user.\n\nWe expect that only official Zulip clients will interact with this data.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this array was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported, and the `type` field in these objects did not\nexist as all onboarding steps were implicitly hotspots.\n", + "items": { + "$ref": "#/components/schemas/OnboardingStep" + } + }, + "navigation_tour_video_url": { + "type": "string", + "nullable": true, + "description": "Present if `onboarding_steps` is present in `fetch_event_types`.\n\nURL of the navigation tour video to display to new users during\nonboarding. If `null`, the onboarding video experience is disabled.\n\n**Changes**: New in Zulip 10.0 (feature level 369).\n" + }, + "max_message_id": { + "type": "integer", + "deprecated": true, + "description": "Present if `message` is present in `fetch_event_types`.\n\nThe highest message ID among all messages the user has received as of the\nmoment of this request.\n\n**Deprecated**: This field may be removed in future versions as it no\nlonger has a clear purpose. Clients wishing to fetch the latest messages\nshould pass `\"anchor\": \"latest\"` to `GET /messages`.\n" + }, + "max_reminder_note_length": { + "type": "integer", + "description": "The maximum allowed length for a reminder note.\n\n**Changes**: New in Zulip 11.0 (feature level 415).\n" + }, + "max_stream_name_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel name, in Unicode code\npoints. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis required `stream` in `fetch_event_types`, was called\n`stream_name_max_length`, and always had a value of 60.\n" + }, + "max_stream_description_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel description, in Unicode\ncode points. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis required `stream` in `fetch_event_types`, was called\n`stream_description_max_length`, and always had a value of 1024.\n" + }, + "max_channel_folder_name_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel folder name, in Unicode\ncode points. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 11.0 (feature level 410). Clients should use\n60 as a fallback value on previous feature levels.\n" + }, + "max_channel_folder_description_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel folder description, in\nUnicode code points. Clients should use this property rather than\nhardcoding field sizes.\n\n**Changes**: New in Zulip 11.0 (feature level 410). Clients should use\n1024 as a fallback value on previous feature levels.\n" + }, + "max_topic_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a topic, in Unicode code points.\nClients should use this property rather than hardcoding field\nsizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis property always had a value of 60.\n" + }, + "max_message_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a message, in Unicode code points.\nClients should use this property rather than hardcoding field\nsizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis property always had a value of 10000.\n" + }, + "server_min_deactivated_realm_deletion_days": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe minimum permitted number of days before full data deletion\n(users, channels, messages, etc.) of a deactivated organization.\nIf `null`, then a deactivated organization's data can be\ndeleted immediately.\n\n**Changes**: New in Zulip 10.0 (feature level 332)\n" + }, + "server_max_deactivated_realm_deletion_days": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum permitted number of days before full data deletion\n(users, channels, messages, etc.) of a deactivated organization.\nIf `null`, then a deactivated organization's data can be\nretained indefinitely.\n\n**Changes**: New in Zulip 10.0 (feature level 332).\n" + }, + "server_presence_ping_interval_seconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing the [presence](/api/get-presence) system,\nthe time interval the client should use for sending presence requests\nto the server (and thus receive presence updates from the server).\n\nIt is important for presence implementations to use both this and\n`server_presence_offline_threshold_seconds` correctly, so that a Zulip\nserver can change these values to manage the trade-off between load and\nfreshness of presence data.\n\n**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 60\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip mobile apps prior to this parameter being introduced.\n" + }, + "server_presence_offline_threshold_seconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nHow old a presence timestamp for a given user can be before the user\nshould be displayed as offline by clients displaying Zulip presence\ndata. See the related `server_presence_ping_interval_seconds` for details.\n\n**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 140\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip client apps prior to this parameter being introduced.\n" + }, + "server_typing_started_expiry_period_milliseconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should wait\nfor additional [typing start](/api/get-events#typing-start) events from\nthe server before removing an active typing indicator.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 15000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" + }, + "server_typing_stopped_wait_period_milliseconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should wait\nwhen a user stops interacting with the compose UI before sending a stop\nnotification to the server.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 5000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" + }, + "server_typing_started_wait_period_milliseconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should use\nto send regular start notifications to the server to indicate that the\nuser is still actively interacting with the compose UI.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 10000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" + }, + "scheduled_messages": { + "type": "array", + "description": "Present if `scheduled_messages` is present in `fetch_event_types`.\n\nAn array of all undelivered scheduled messages by the user.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", + "items": { + "$ref": "#/components/schemas/ScheduledMessage" + } + }, + "reminders": { + "type": "array", + "description": "Present if `reminders` is present in `fetch_event_types`.\n\nAn array of all undelivered reminders scheduled by the user.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", + "items": { + "$ref": "#/components/schemas/ScheduledMessage" + } + }, + "muted_topics": { + "type": "array", + "deprecated": true, + "description": "Present if `muted_topics` is present in `fetch_event_types`.\n\nArray of tuples, where each tuple describes a muted topic.\nThe first element of the tuple is the channel name in which the topic\nhas to be muted, the second element is the topic name to be muted\nand the third element is an integer UNIX timestamp representing\nwhen the topic was muted.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting\nwith this version, `muted_topics` will only be present in the\nresponse if the `user_topic` object, which generalizes and replaces\nthis field, is not explicitly requested via `fetch_event_types`.\n\nBefore Zulip 3.0 (feature level 1), the `muted_topics`\narray objects were 2-item tuples and did not include the timestamp\ninformation for when the topic was muted.\n", + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + } + ] + } + } + }, + "muted_users": { + "type": "array", + "description": "Present if `muted_users` is present in `fetch_event_types`.\n\nA list of dictionaries where each dictionary describes\na [muted user](/api/mute-user).\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the user ID and timestamp of a muted user.\n", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the muted user.\n" + }, + "timestamp": { + "type": "integer", + "description": "An integer UNIX timestamp representing when the user was muted.\n" + } + } + } + }, + "presences": { + "type": "object", + "description": "Present if `presence` is present in `fetch_event_types`.\n\nA dictionary where each entry describes the presence details of a\nuser in the Zulip organization.\n\nThe format of the entry (modern or legacy) depends on the value of\n[`slim_presence`](#parameter-slim_presence).\n\nUsers who have been offline for multiple weeks may not appear in this object.\n", + "additionalProperties": { + "type": "object", + "description": "Will be one of these two formats (modern or legacy) for user\npresence data:\n", + "oneOf": [ + { + "$ref": "#/components/schemas/ModernPresenceFormat" + }, + { + "type": "object", + "description": "`{user_email}`: Presence data (legacy format) for the user with\nthe specified Zulip API email.\n", + "additionalProperties": { + "$ref": "#/components/schemas/LegacyPresenceFormat" + } + } + ] + } + }, + "presence_last_update_id": { + "type": "integer", + "description": "Present if `presence` is present in `fetch_event_types`.\n\nProvides the `last_update_id` value of the latest presence data fetched by\nthe server and included in the response in `presences`. This can be used\nas the value of the `presence_last_update_id` parameter when polling\nfor presence data at the [/users/me/presence](/api/update-presence) endpoint\nto tell the server to only fetch the relevant newer data in order to skip\nredundant already-known presence information.\n\n**Changes**: New in Zulip 9.0 (feature level 263).\n" + }, + "server_timestamp": { + "type": "number", + "description": "Present if `presence` is present in `fetch_event_types`.\n\nThe time when the server fetched the\n`presences` data included in the response.\nMatches the similar field in presence\nresponses.\n\n**Changes**: New in Zulip 5.0 (feature level 70).\n" + }, + "realm_domains": { + "type": "array", + "description": "Present if `realm_domains` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a domain within\nwhich users can join the organization without and invitation.\n", + "items": { + "$ref": "#/components/schemas/RealmDomain" + } + }, + "realm_emoji": { + "description": "Present if `realm_emoji` is present in `fetch_event_types`.\n\nA dictionary of objects where each object describes a custom\nemoji that has been uploaded in this Zulip organization.\n", + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/RealmEmoji" + } + }, + "realm_linkifiers": { + "type": "array", + "description": "Present if `realm_linkifiers` is present in `fetch_event_types`.\n\nAn ordered array of objects where each object describes a single\n[linkifier](/help/add-a-custom-linkifier).\n\nThe order of the array reflects the order that each\nlinkifier should be processed when linkifying messages\nand topics. By default, new linkifiers are ordered\nlast. This order can be modified with [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n\nClients will receive an empty array unless the event queue is\nregistered with the client capability `{\"linkifier_url_template\": true}`.\nSee [`client_capabilities`](/api/register-queue#parameter-client_capabilities)\nparameter for how this can be specified.\n\n**Changes**: Before Zulip 7.0 (feature level 176), the\n`linkifier_url_template` client capability was not required. The\nrequirement was added because linkifiers were updated to contain\na URL template instead of a URL format string, which was a not\nbackwards-compatible change.\n\nNew in Zulip 4.0 (feature level 54). Clients can access this data for\nservers on earlier feature levels via the legacy `realm_filters` property.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "pattern": { + "type": "string", + "description": "The [Python regular expression](https://docs.python.org/3/howto/regex.html)\npattern which represents the pattern that should be linkified on matching.\n" + }, + "url_template": { + "type": "string", + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL\ntemplate with which the pattern matching string should be linkified.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the linkifier.\n" + } + } + } + }, + "realm_filters": { + "type": "array", + "deprecated": true, + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "integer" + }, + { + "type": "string" + } + ] + } + }, + "description": "Legacy property for [linkifiers](/help/add-a-custom-linkifier).\nPresent if `realm_filters` is present in `fetch_event_types`.\n\nWhen present, this is always an empty array.\n\n**Changes**: Prior to Zulip 7.0 (feature level 176), this was\nan array of tuples, where each tuple described a linkifier. The first\nelement of the tuple was a string regex pattern which represented the\npattern to be linkified on matching, for example `\"#(?P[123])\"`.\nThe second element was a URL format string that the pattern should be\nlinkified with. A URL format string for the above example would be\n`\"https://realm.com/my_realm_filter/%(id)s\"`. And the third element\nwas the ID of the realm filter.\n\n**Deprecated** in Zulip 4.0 (feature level 54), replaced by the\n`realm_linkifiers` key.\n" + }, + "realm_playgrounds": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RealmPlayground" + }, + "description": "Present if `realm_playgrounds` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a\n[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n" + }, + "realm_user_groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserGroup" + }, + "description": "Present if `realm_user_groups` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a\n[user group](/help/user-groups) in the Zulip organization.\n\nDeactivated groups will only be included if `include_deactivated_groups`\nclient capability is set to `true`.\n\n**Changes**: Prior to Zulip 10.0 (feature level 294), deactivated\ngroups were included for all the clients.\n" + }, + "realm_bots": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Bot" + }, + "description": "Present if `realm_bot` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a bot that the\ncurrent user can administer. If the current user is an organization\nadministrator, this will include all bots in the organization. Otherwise,\nit will only include bots owned by the user (either because the user created\nthe bot or an administrator transferred the bot's ownership to the user).\n" + }, + "realm_embedded_bots": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of an embedded bot. Embedded bots are an experimental\nfeature not enabled in production yet.\n", + "properties": { + "name": { + "type": "string", + "description": "The name of the bot.\n" + }, + "config": { + "$ref": "#/components/schemas/BotConfiguration" + } + } + }, + "description": "Present if `realm_embedded_bots` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes an type of embedded\nbot that is available to be configured on this Zulip server.\n\nClients only need these data if they contain UI for creating or administering bots.\n" + }, + "realm_incoming_webhook_bots": { + "description": "Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a type of incoming webhook\nintegration that is available to be configured on this Zulip server.\n\nClients only need these data if they contain UI for creating or administering bots.\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of the bot.\n", + "properties": { + "name": { + "type": "string", + "description": "A machine-readable unique name identifying the integration, all-lower-case without\nspaces.\n" + }, + "display_name": { + "type": "string", + "description": "A human-readable display name identifying the integration that this bot implements,\nintended to be used in menus for selecting which integration to create.\n\n**Changes**: New in Zulip 8.0 (feature level 207).\n" + }, + "all_event_types": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "For incoming webhook integrations that support the Zulip server filtering incoming\nevents, the list of event types supported by it.\n\nA null value will be present if this incoming webhook integration doesn't support\nsuch filtering.\n\n**Changes**: New in Zulip 8.0 (feature level 207).\n" + }, + "config_options": { + "$ref": "#/components/schemas/WebhookConfigOption" + }, + "url_options": { + "$ref": "#/components/schemas/WebhookUrlOption" + } + } + } + }, + "recent_private_conversations": { + "description": "Present if `recent_private_conversations` is present in `fetch_event_types`.\n\nAn array of dictionaries containing data on all direct message and group direct message\nconversations that the user has received (or sent) messages in, organized by\nconversation. This data set is designed to support UI elements such as the\n\"Direct messages\" widget in the web application showing recent direct message\nconversations that the user has participated in.\n\n\"Recent\" is defined as the server's discretion; the original implementation\ninterpreted that as \"the 1000 most recent direct messages the user received\".\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "description": "Object describing a single recent direct conversation in the user's history.\n", + "properties": { + "max_message_id": { + "type": "integer", + "description": "The highest message ID of the conversation, intended to support sorting\nthe conversations by recency.\n" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "The list of users other than the current user in the direct message\nconversation. This will be an empty list for direct messages sent to\noneself.\n" + } + } + } + }, + "navigation_views": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NavigationView" + }, + "description": "Present if `navigation_views` is present in `fetch_event_types`.\nAn array of dictionaries containing data on all of the current user's\nnavigation views.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" + }, + "saved_snippets": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SavedSnippet" + }, + "description": "Present if `saved_snippets` is present in `fetch_event_types`.\n\nAn array of dictionaries containing data on all of the current user's\nsaved snippets.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" + }, + "subscriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Subscription" + }, + "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes the properties\nof a channel the user is subscribed to (as well as that user's\npersonal per-channel settings).\n\n**Changes**: Removed `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n" + }, + "unsubscribed": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Subscription" + }, + "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes one of the\nchannels the user has unsubscribed from but was previously subscribed to\nalong with the subscription details.\n\nUnlike `never_subscribed`, the user might have messages in their personal\nmessage history that were sent to these channels.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), if a user was\nin `can_administer_channel_group` of a channel that they had\nunsubscribed from, but not an organization administrator, the channel\nin question would not be part of this array.\n\nRemoved `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n" + }, + "never_subscribed": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/BasicChannelBase" + }, + { + "additionalProperties": false, + "properties": { + "stream_id": {}, + "name": {}, + "is_archived": {}, + "description": {}, + "date_created": {}, + "creator_id": { + "nullable": true + }, + "invite_only": {}, + "rendered_description": {}, + "is_web_public": {}, + "stream_post_policy": {}, + "message_retention_days": { + "nullable": true + }, + "history_public_to_subscribers": {}, + "topics_policy": {}, + "first_message_id": { + "nullable": true + }, + "folder_id": { + "nullable": true + }, + "is_recently_active": {}, + "is_announcement_only": {}, + "can_add_subscribers_group": {}, + "can_remove_subscribers_group": {}, + "can_administer_channel_group": {}, + "can_delete_any_message_group": {}, + "can_delete_own_message_group": {}, + "can_move_messages_out_of_channel_group": {}, + "can_move_messages_within_channel_group": {}, + "can_send_message_group": {}, + "can_subscribe_group": {}, + "can_resolve_topics_group": {}, + "subscriber_count": {}, + "stream_weekly_traffic": { + "type": "integer", + "nullable": true, + "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, the channel was recently created and there is\ninsufficient data to estimate the average traffic.\n" + }, + "subscribers": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A list of user IDs of users who are subscribed\nto the channel. Included only if `include_subscribers` is `true`.\n\nIf a user is not allowed to know the subscribers for\na channel, we will send an empty array. API authors\nshould use other data to determine whether users like\nguest users are forbidden to know the subscribers.\n" + }, + "partial_subscribers": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "If [`include_subscribers=\"partial\"`](/api/get-subscriptions#parameter-include_subscribers)\nwas requested, the server may, at its discretion, send a\n`partial_subscribers` list rather than a `subscribers` list\nfor channels with a large number of subscribers.\n\nThe `partial_subscribers` list contains an arbitrary\nsubset of the channel's subscribers that is guaranteed\nto include all bot user subscribers as well as all\nusers who have been active in the last 14 days, but\notherwise can be chosen arbitrarily by the server.\n\nIf a user is not allowed to know the subscribers for\na channel, we will send an empty array. API authors\nshould use other data to determine whether users like\nguest users are forbidden to know the subscribers.\n\n**Changes**: New in Zulip 11.0 (feature level 412).\n" + } + } + } + ] + }, + "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes one of the\nchannels that is visible to the user and the user has never been subscribed\nto.\n\nImportant for clients containing UI where one can browse channels to subscribe\nto.\n\n**Changes**: Before Zulip 10.0 (feature level 362), archived channels did\nnot appear in this list, even if the `archived_channels` [client\ncapability][client-capabilities] was declared by the client.\n\nPrior to Zulip 10.0 (feature level 349), if a user was\nin `can_administer_channel_group` of a channel that they never\nsubscribed to, but not an organization administrator, the channel\nin question would not be part of this array.\n" + }, + "channel_folders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelFolder" + }, + "description": "Present if `channel_folders` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes one\nof the channel folders in the organization.\n\nOnly channel folders with one or more public web channels are\nvisible to spectators.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" + }, + "unread_msgs": { + "type": "object", + "description": "Present if `message` and `update_message_flags` are both present in\n`event_types`.\n\nA set of data structures describing the conversations containing\nthe 50000 most recent unread messages the user has received. This will usually\ncontain every unread message the user has received, but clients should support\nusers with even more unread messages (and not hardcode the number 50000).\n", + "additionalProperties": false, + "properties": { + "count": { + "type": "integer", + "description": "The total number of unread messages to display. This includes one-on-one and group\ndirect messages, as well as channel messages that are not [muted](/help/mute-a-topic).\n\n**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow\ntopic features were not handled correctly in calculating this field.\n" + }, + "pms": { + "type": "array", + "description": "An array of objects where each object contains details of unread\none-on-one direct messages with a specific user.\n\nNote that it is possible for a message that the current user sent\nto the specified user to be marked as unread and thus appear here.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "other_user_id": { + "type": "integer", + "description": "The user ID of the other participant in this one-on-one direct\nmessage conversation. Will be the current user's ID for messages\nthat they sent in a one-on-one direct message conversation with\nthemself.\n\n**Changes**: New in Zulip 5.0 (feature level 119), replacing\nthe less clearly named `sender_id` field.\n" + }, + "sender_id": { + "deprecated": true, + "type": "integer", + "description": "Old name for the `other_user_id` field. Clients should access\nthis field in Zulip server versions that do not yet support\n`other_user_id`.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 119).\nWe expect to provide a next version of the full `unread_msgs`\nAPI before removing this legacy name.\n" + }, + "unread_message_ids": { + "type": "array", + "description": "The message IDs of the recent unread direct messages sent\nby either user in this one-on-one direct message conversation,\nsorted in ascending order.\n", + "items": { + "type": "integer" + } + } + } + } + }, + "streams": { + "type": "array", + "description": "An array of dictionaries where each dictionary contains details of all\nunread messages of a single subscribed channel. This includes muted channels\nand muted topics, even though those messages are excluded from `count`.\n\n**Changes**: Prior to Zulip 5.0 (feature level 90), these objects\nincluded a `sender_ids` property, which listed the set of IDs of\nusers who had sent the unread messages.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "topic": { + "type": "string", + "description": "The topic under which the messages were sent.\n\nNote that the empty string topic may have been rewritten by the server\nto the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response depending on the value\nof the `empty_topic_name` [client capability][client-capabilities].\n\n**Changes**: The `empty_topic_name` client capability is new in\nZulip 10.0 (feature level 334).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "stream_id": { + "type": "integer", + "description": "The ID of the channel to which the messages were sent.\n" + }, + "unread_message_ids": { + "type": "array", + "description": "The message IDs of the recent unread messages sent in this channel,\nsorted in ascending order.\n", + "items": { + "type": "integer" + } + } + } + } + }, + "huddles": { + "type": "array", + "description": "An array of objects where each object contains details of unread\ngroup direct messages with a specific group of users.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "user_ids_string": { + "type": "string", + "description": "A string containing the IDs of all users in the group\ndirect message conversation, including the current user,\nseparated by commas and sorted numerically; for example:\n`\"1,2,3\"`.\n" + }, + "unread_message_ids": { + "type": "array", + "description": "The message IDs of the recent unread messages which have been sent in\nthis group direct message conversation, sorted in ascending order.\n", + "items": { + "type": "integer" + } + } + } + } + }, + "mentions": { + "type": "array", + "description": "Array containing the IDs of all unread messages in which the user was\nmentioned directly, and unread [non-muted](/help/mute-a-topic) messages\nin which the user was mentioned through a wildcard.\n\n**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow\ntopic features were not handled correctly in calculating this field.\n", + "items": { + "type": "integer" + } + }, + "old_unreads_missing": { + "type": "boolean", + "description": "Whether this data set was truncated because the user has too many\nunread messages. When truncation occurs, only the most recent\n`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered\nwhen forming this response. When `true`, we recommend that clients\ndisplay a warning, as they are likely to produce erroneous results\nuntil reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`\nunread messages.\n\n**Changes**: New in Zulip 4.0 (feature level 44).\n" + } + } + }, + "starred_messages": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Present if `starred_messages` is present in `fetch_event_types`.\n\nArray containing the IDs of all messages which have been\n[starred](/help/star-a-message) by the user.\n" + }, + "streams": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BasicChannel" + }, + "description": "Present if `stream` is present in `fetch_event_types`.\n\nArray of dictionaries where each dictionary contains details about\na single channel in the organization that is visible to the user.\n\nFor organization administrators, this will include all private channels\nin the organization.\n\n**Changes**: Before Zulip 11.0 (feature level 378), archived channels\ndid not appear in this list, even if the `archived_channels` [client\ncapability][client-capabilities] was declared by the client.\n\nAs of Zulip 8.0 (feature level 205), this will include all web-public\nchannels in the organization as well.\n" + }, + "realm_default_streams": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Present if `default_streams` is present in `fetch_event_types`.\n\nAn array of IDs of all the [default channels](/help/set-default-streams-for-new-users)\nin the organization.\n\n**Changes**: Before Zulip 10.0 (feature level 330), we sent\narray of dictionaries where each dictionary contained details\nabout a single default stream for the Zulip organization.\n" + }, + "realm_default_stream_groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DefaultChannelGroup" + }, + "description": "Present if `default_stream_groups` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary contains details\nabout a single default channel group configured for this\nZulip organization.\n\nDefault channel groups are an experimental feature.\n" + }, + "stop_words": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Present if `stop_words` is present in `fetch_event_types`.\n\nAn array containing the stop words used by the Zulip server's\nfull-text search implementation. Useful for showing helpful\nerror messages when a search returns limited results because\na stop word in the query was ignored.\n" + }, + "user_status": { + "type": "object", + "description": "Present if `user_status` is present in `fetch_event_types`.\n\nA dictionary which contains the [status](/help/status-and-availability)\nof all users in the Zulip organization who have set a status.\n\n**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).\nPreviously, Zulip did not support emoji associated with statuses.\n", + "additionalProperties": { + "allOf": [ + { + "description": "`{user_id}`: Object containing the status details of a user\nwith the key of the object being the ID of the user.\n" + }, + { + "$ref": "#/components/schemas/UserStatus" + } + ] + } + }, + "user_settings": { + "type": "object", + "description": "Present if `user_settings` is present in `fetch_event_types`.\n\nA dictionary containing the user's personal settings.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0\n(feature level 364) as we now have `web_font_size_px` and\n`web_line_height_percent` settings for more control.\n\nNew in Zulip 5.0 (feature level 89). Previously, these\nsettings appeared in the top-level object, where they are\navailable for clients without the `user_settings_object` client\ncapability for backwards-compatibility.\n", + "additionalProperties": false, + "properties": { + "twenty_four_hour_time": { + "type": "boolean", + "nullable": true, + "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\nA `null` value indicates that the client should use the default time\nformat for the user's locale.\n\n**Changes**: Prior to Zulip 11.0 (feature level 408), `null`\nwas not a valid value for this setting. Note that it was not possible\nto actually set the time format to `null` at this feature level.\n" + }, + "web_mark_read_on_scroll_policy": { + "type": "integer", + "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n" + }, + "web_channel_default_view": { + "type": "integer", + "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n" + }, + "starred_message_counts": { + "type": "boolean", + "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n" + }, + "receives_typing_notifications": { + "type": "boolean", + "description": "Whether the user is configured to receive typing notifications from\nother users. The server will only deliver typing notifications events\nto users who for whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" + }, + "web_suggest_update_timezone": { + "type": "boolean", + "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n" + }, + "fluid_layout_width": { + "type": "boolean", + "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n" + }, + "high_contrast_mode": { + "type": "boolean", + "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n" + }, + "web_font_size_px": { + "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", + "type": "integer", + "example": 14 + }, + "web_line_height_percent": { + "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", + "type": "integer", + "example": 122 + }, + "color_scheme": { + "type": "integer", + "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n" + }, + "translate_emoticons": { + "type": "boolean", + "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n" + }, + "display_emoji_reaction_users": { + "type": "boolean", + "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting\nusers, rather than a count, for messages with few total\nreactions. The ideal cutoff may depend on the space\navailable for displaying reactions; the official web\napplication displays names when 3 or fewer total reactions\nare present with this setting enabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n" + }, + "default_language": { + "type": "string", + "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n" + }, + "web_home_view": { + "type": "string", + "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n" + }, + "web_escape_navigates_to_home_view": { + "type": "boolean", + "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n" + }, + "left_side_userlist": { + "type": "boolean", + "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n" + }, + "emojiset": { + "type": "string", + "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n" + }, + "demote_inactive_streams": { + "type": "integer", + "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n" + }, + "user_list_style": { + "type": "integer", + "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n" + }, + "web_animate_image_previews": { + "type": "string", + "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n" + }, + "web_stream_unreads_count_display_policy": { + "type": "integer", + "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n" + }, + "hide_ai_features": { + "type": "boolean", + "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + }, + "web_left_sidebar_show_channel_folders": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n" + }, + "web_left_sidebar_unreads_count_summary": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n" + }, + "timezone": { + "type": "string", + "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n" + }, + "enter_sends": { + "type": "boolean", + "description": "Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)\nin the compose box is enabled.\n" + }, + "enable_drafts_synchronization": { + "type": "boolean", + "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n" + }, + "enable_stream_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for channel messages.\n" + }, + "enable_stream_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for channel messages.\n" + }, + "enable_stream_push_notifications": { + "type": "boolean", + "description": "Enable mobile notifications for channel messages.\n" + }, + "enable_stream_audible_notifications": { + "type": "boolean", + "description": "Enable audible desktop notifications for channel messages.\n" + }, + "notification_sound": { + "type": "string", + "description": "Notification sound name.\n" + }, + "enable_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for direct messages and @-mentions.\n" + }, + "enable_sounds": { + "type": "boolean", + "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n" + }, + "enable_followed_topic_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_push_notifications": { + "type": "boolean", + "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_audible_notifications": { + "type": "boolean", + "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "email_notifications_batching_period_seconds": { + "type": "integer", + "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n" + }, + "enable_offline_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n" + }, + "enable_offline_push_notifications": { + "type": "boolean", + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n" + }, + "enable_online_push_notifications": { + "type": "boolean", + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n" + }, + "enable_digest_emails": { + "type": "boolean", + "description": "Enable digest emails when the user is away.\n" + }, + "enable_marketing_emails": { + "type": "boolean", + "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n" + }, + "enable_login_emails": { + "type": "boolean", + "description": "Enable email notifications for new logins to account.\n" + }, + "message_content_in_email_notifications": { + "type": "boolean", + "description": "Include the message's content in email notifications for new messages.\n" + }, + "pm_content_in_desktop_notifications": { + "type": "boolean", + "description": "Include content of direct messages in desktop notifications.\n" + }, + "wildcard_mentions_notify": { + "type": "boolean", + "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n" + }, + "enable_followed_topic_wildcard_mentions_notify": { + "type": "boolean", + "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "desktop_icon_count_display": { + "type": "integer", + "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,\nand followed topics` option, renumbering the options to insert it in\norder.\n" + }, + "realm_name_in_email_notifications_policy": { + "type": "integer", + "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n" + }, + "automatically_follow_topics_policy": { + "type": "integer", + "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "type": "integer", + "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" + }, + "automatically_follow_topics_where_mentioned": { + "type": "boolean", + "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n" + }, + "resolved_topic_notice_auto_read_policy": { + "type": "string", + "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n" + }, + "presence_enabled": { + "type": "boolean", + "description": "Display the presence status to other users when online.\n" + }, + "available_notification_sounds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Array containing the names of the notification sound options\nsupported by this Zulip server. Only relevant to support UI\nfor configuring notification sounds.\n" + }, + "emojiset_choices": { + "description": "Array of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n", + "type": "array", + "items": { + "type": "object", + "description": "Object describing a emoji set.\n", + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" + }, + "text": { + "type": "string", + "description": "The text describing the emoji set.\n" + } + } + } + }, + "send_private_typing_notifications": { + "type": "boolean", + "description": "Whether the user has chosen to send [typing\nnotifications](/help/typing-notifications)\nwhen composing direct messages. The client should send typing\nnotifications for direct messages if and only if this setting is enabled.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "send_stream_typing_notifications": { + "type": "boolean", + "description": "Whether the user has chosen to send [typing\nnotifications](/help/typing-notifications)\nwhen composing channel messages. The client should send typing\nnotifications for channel messages if and only if this setting is enabled.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "send_read_receipts": { + "type": "boolean", + "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "allow_private_data_export": { + "type": "boolean", + "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n" + }, + "email_address_visibility": { + "$ref": "#/components/schemas/EmailAddressVisibility" + }, + "web_navigate_to_sent_message": { + "type": "boolean", + "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n" + } + } + }, + "user_topics": { + "type": "array", + "description": "Present if `user_topic` is present in `fetch_event_types`.\n\n**Changes**: New in Zulip 6.0 (feature level 134), deprecating and\nreplacing the previous `muted_topics` structure.\n", + "items": { + "type": "object", + "description": "Object describing the user's configuration for a given topic.\n", + "additionalProperties": false, + "properties": { + "stream_id": { + "type": "integer", + "description": "The ID of the channel to which the topic belongs.\n" + }, + "topic_name": { + "type": "string", + "description": "The name of the topic.\n\nNote that the empty string topic may have been rewritten by the server to\nthe value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue)\nresponse depending on the value of the `empty_topic_name` [client capability][client-capabilities].\n\n**Changes**: The `empty_topic_name` client capability is new in\nZulip 10.0 (feature level 334).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "last_updated": { + "type": "integer", + "description": "An integer UNIX timestamp representing when the user-topic\nrelationship was changed.\n" + }, + "visibility_policy": { + "type": "integer", + "description": "An integer indicating the user's visibility configuration for\nthe topic.\n\n- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).\n- 2 = Unmuted. Used to record [unmuted topics](/help/mute-a-topic).\n- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n\nIn Zulip 7.0 (feature level 170), added unmuted as a visibility\npolicy option.\n" + } + } + } + }, + "has_zoom_token": { + "type": "boolean", + "description": "Present if `video_calls` is present in `fetch_event_types`.\n\nA boolean which signifies whether the user has a Zoom token and has thus\ncompleted OAuth flow for the [Zoom integration](/help/configure-call-provider).\nClients need to know whether initiating Zoom OAuth is required before\ncreating a Zoom call.\n" + }, + "giphy_api_key": { + "type": "string", + "description": "Present if `giphy` is present in `fetch_event_types`.\n\nGIPHY's client-side SDKs needs this API key to use the GIPHY API.\nGIPHY API keys are not secret (their main purpose appears to be\nallowing GIPHY to block a problematic app). Please don't use our API\nkey for an app unrelated to Zulip.\n\nDevelopers of clients should also read the\n[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)\nbefore using this API key.\n\n**Changes**: Added in Zulip 4.0 (feature level 47).\n" + }, + "push_devices": { + "type": "object", + "description": "Present if `push_device` is present in `fetch_event_types`.\n\nDictionary where each entry describes the user's push device's\nregistration status and error code (if registration failed).\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", + "additionalProperties": { + "description": "`{push_account_id}`: Dictionary containing the details of\na push device with the push account ID as the key.\n", + "type": "object", + "additionalProperties": false, + "properties": { + "status": { + "type": "string", + "description": "The push account's registration status.\nEither `\"active\"`, `\"pending\"`, or `\"failed\"`.\n" + }, + "error_code": { + "type": "string", + "nullable": true, + "description": "If the status is `\"failed\"`, a [Zulip API error\ncode](/api/rest-error-handling) indicating the type of failure that\noccurred.\n\nThe following error codes have recommended client behavior:\n\n- `\"INVALID_BOUNCER_PUBLIC_KEY\"` - Inform the user to update app.\n- `\"REQUEST_EXPIRED` - Retry with a fresh payload.\n" + } + } + } + }, + "enable_desktop_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_digest_emails": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_login_emails": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_marketing_emails": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "email_notifications_batching_period_seconds": { + "deprecated": true, + "type": "integer", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_offline_email_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_offline_push_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_online_push_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_sounds": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_stream_desktop_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_stream_email_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_stream_push_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_stream_audible_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "wildcard_mentions_notify": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "message_content_in_email_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "notification_sound": { + "deprecated": true, + "type": "string", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "pm_content_in_desktop_notifications": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "desktop_icon_count_display": { + "deprecated": true, + "type": "integer", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "realm_name_in_email_notifications_policy": { + "deprecated": true, + "type": "integer", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: In Zulip 7.0 (feature level 168), replaced previous\n`realm_name_in_notifications` global notifications setting with\n`realm_name_in_email_notifications_policy`.\n\n**Deprecated** since Zulip 5.0 (feature level 89); both\n`realm_name_in_notifications` and the newer\n`realm_name_in_email_notifications_policy` are deprecated. Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "presence_enabled": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "available_notification_sounds": { + "deprecated": true, + "type": "array", + "items": { + "type": "string" + }, + "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nArray containing the names of the notification sound options supported by\nthis Zulip server. Only relevant to support UI for configuring notification\nsounds.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "color_scheme": { + "deprecated": true, + "type": "integer", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe color scheme selected by the user.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "default_language": { + "deprecated": true, + "type": "string", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe default language chosen by the user.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "demote_inactive_streams": { + "deprecated": true, + "type": "integer", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen to hide inactive channels.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "emojiset": { + "deprecated": true, + "type": "string", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe name of the emoji set that the user has chosen.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "enable_drafts_synchronization": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether drafts synchronization is enabled for the user. If disabled,\nclients will receive an error when trying to use the `drafts` endpoints.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\nNew in Zulip 5.0 (feature level 87).\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "fluid_layout_width": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for the layout width to be fluid.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "web_home_view": { + "deprecated": true, + "type": "string", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe [home view](/help/configure-home-view) in Zulip, represented\nas the URL suffix after `#` to be rendered when Zulip loads.\n\nCurrently supported values are `all_messages` and `recent_topics`.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n\n**Deprecated** in Zulip 5.0 (feature level 89). Clients connecting to newer\nservers should declare the `user_settings_object` client capability and\naccess the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "high_contrast_mode": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether has switched on high contrast mode.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "left_side_userlist": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for the userlist to be displayed\non the left side of the screen (for desktop app and web app) in narrow\nwindows.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "starred_message_counts": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen the number of starred messages to\nbe displayed similar to unread counts.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "timezone": { + "deprecated": true, + "type": "string", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe user's [profile time zone](/help/change-your-timezone), which is\nused primarily to display the user's local time to other users.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "translate_emoticons": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for emoticons to be translated into emoji\nin the Zulip compose box.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "twenty_four_hour_time": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen a twenty four hour time display (true)\nor a twelve hour one (false).\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "receives_typing_notifications": { + "type": "boolean", + "description": "Whether the user is configured to receive typing notifications from other\nusers. The server will only deliver typing notifications events to users who\nfor whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" + }, + "enter_sends": { + "deprecated": true, + "type": "boolean", + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user setting for [sending on pressing Enter][set-enter-send]\nin the compose box is enabled.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and process the `user_settings` event type instead.\n\nPrior to Zulip 5.0 (feature level 84), this field was present\nin response if `realm_user` was present in `fetch_event_types`, not\n`update_display_settings`.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n[set-enter-send]: /help/configure-send-message-keys\n" + }, + "emojiset_choices": { + "deprecated": true, + "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nArray of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n", + "type": "array", + "items": { + "type": "object", + "description": "Object describing a emoji set.\n", + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" + }, + "text": { + "type": "string", + "description": "The text describing the emoji set.\n" + } + } + } + }, + "realm_message_edit_history_visibility_policy": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhat typesof message edit history are accessible to users via\n[message edit history](/help/view-a-messages-edit-history).\n\n- \"all\" = All edit history is visible.\n- \"moves\" = Only moves are visible.\n- \"none\" = No edit history is visible.\n\n**Changes**: New in Zulip 10.0 (feature level 358), replacing the previous\n`allow_edit_history` boolean setting; `true` corresponds to `all`,\nand `false` to `none`.\n" + }, + "realm_allow_edit_history": { + "deprecated": true, + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization is configured to allow users to access\n[message edit history](/help/view-a-messages-edit-history).\n\nThe value of `realm_allow_edit_history` is set as `false` if the\n`realm_message_edit_history_visibility_policy` is configured as \"None\"\nand `true` if it is configured as \"Moves only\" or \"All\".\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 358) and will be\nremoved in the future, as it is an inaccurate version\n`realm_message_edit_history_visibility_policy`, which replaces this field.\n" + }, + "realm_can_add_custom_emoji_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add custom emoji in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 307). Previously, this\npermission was controlled by the enum `add_custom_emoji_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n\nBefore Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`\nboolean setting controlled this permission; `true` corresponded to `Admins`,\nand `false` to `Everyone`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_add_subscribers_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add subscribers to channels in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 341). Previously, this\npermission was controlled by the enum `invite_to_stream_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_delete_any_message_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete any message in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 281). Previously, this\npermission was limited to administrators only and was uneditable.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_delete_own_message_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete messages that they have sent in the\norganization.\n\n**Changes**: New in Zulip 10.0 (feature level 291). Previously, this\npermission was controlled by the enum `delete_own_message_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.\n\nBefore Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean\nsetting controlled this permission; `true` corresponded to `Everyone`, and\n`false` to `Admins`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_set_delete_message_policy_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `can_delete_any_message_group`\nand `can_delete_own_message_group` permission settings. Note that the user\nmust be a member of both this group and the `can_administer_channel_group`\nof the channel whose message delete settings they want to change.\n\nOrganization administrators can always change these settings of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_set_topics_policy_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `topics_policy` setting. Note that\nthe user must be a member of both this group and the `can_administer_channel_group`\nof the channel whose `topics_policy` they want to change.\n\nOrganization administrators can always change the `topics_policy` setting of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 392).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_invite_users_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to send email invitations for inviting other users\nto the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 321). Previously, this\npermission was controlled by the enum `invite_to_realm_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nBefore Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean\nsetting controlled this permission; `true` corresponded to `Admins`, and\n`false` to `Members`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_mention_many_users_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using mentions in large\nchannels, even when permitted to do so.\n\n**Changes**: New in Zulip 10.0 (feature level 352). Previously, this\npermission was controlled by the enum `wildcard_mention_policy`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_move_messages_between_channels_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one channel to another\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 310). Previously, this\npermission was controlled by the enum `move_messages_between_streams_policy`.\nValues were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`move_messages_between_streams_policy` enum.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_move_messages_between_topics_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one topic to another\nwithin a channel in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 316). Previously, this\npermission was controlled by the enum `edit_topic_policy`. Values were\n1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`edit_topic_policy` enum.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_can_create_groups": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create user\ngroups in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 299). Previously\n`realm_user_group_edit_policy` field used to control the\npermission to create user groups.\n" + } + ] + }, + "realm_can_create_bots_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create all types of bot users\nin the organization. See also `can_create_write_only_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" + } + ] + }, + "realm_can_create_write_only_bots_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create bot users that\ncan only send messages in the organization, i.e. incoming webhooks,\nin addition to the users who are present in `can_create_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" + } + ] + }, + "realm_can_manage_all_groups": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + } + ] + }, + "realm_can_manage_billing_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to manage plans and billing in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners\nand users with `is_billing_admin` property set to `true` were allowed to\nmanage plans and billing.\n" + } + ] + }, + "realm_can_create_public_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create public\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 264). Previously\n`realm_create_public_stream_policy` field used to control the\npermission to create public channels.\n" + } + ] + }, + "realm_can_create_private_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create private\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 266). Previously\n`realm_create_private_stream_policy` field used to control the\npermission to create private channels.\n" + } + ] + }, + "realm_can_create_web_public_channel_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create web-public\nchannels in this organization.\n\nHas no effect and should not be displayed in settings UI\nunless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`\nserver-level setting enabled and the organization has enabled\nthe `enable_spectator_access` realm setting.\n\n**Changes**: New in Zulip 10.0 (feature level 280). Previously\n`realm_create_web_public_stream_policy` field used to control\nthe permission to create web-public channels.\n" + } + ] + }, + "realm_can_resolve_topics_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to [resolve topics](/help/resolve-a-topic)\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 367). Previously, permission\nto resolve topics was controlled by the more general\n`can_move_messages_between_topics_group permission for moving messages`.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_create_public_stream_policy": { + "type": "integer", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create public channels in the organization,\navailable for backwards-compatibility. Clients should use\n`can_create_public_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Members only\n- 2 = Admins only\n- 3 = [Full members][calc-full-member] only\n- 4 = Admins and moderators only\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 264) and\nreplaced by `realm_can_create_public_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\nBefore Zulip 5.0 (feature level 102), permission to create\nchannels was controlled by the `realm_create_stream_policy` setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "realm_create_private_stream_policy": { + "type": "integer", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create private channels in the organization,\navailable for backwards-compatibility. Clients should use\n`can_create_private_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Members only\n- 2 = Admins only\n- 3 = [Full members][calc-full-member] only\n- 4 = Admins and moderators only\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 266) and\nreplaced by `realm_can_create_private_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\n**Changes**: Before Zulip 5.0 (feature level 102), permission to\ncreate channels was controlled by the `realm_create_stream_policy` setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "realm_create_web_public_stream_policy": { + "type": "integer", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create web-public channels in the\norganization, available for backwards-compatibility. Clients\nshould use `can_create_web_public_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 2 = Admins only\n- 4 = Admins and moderators only\n- 6 = Nobody\n- 7 = Owners only\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 280) and\nreplaced by `realm_can_create_web_public_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\n**Changes**: Added in Zulip 5.0 (feature level 103).\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n" + }, + "realm_wildcard_mention_policy": { + "type": "integer", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to use wildcard mentions in large channels,\navailable for backwards-compatibility. Clients should use\n`can_mention_many_users_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can use wildcard mentions in large channels.\n- 2 = Only members can use wildcard mentions in large channels.\n- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.\n- 5 = Only organization administrators can use wildcard mentions in large channels.\n- 6 = Nobody can use wildcard mentions in large channels.\n- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using\nmentions in large channels, even when permitted to do so.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 352) and\nreplaced by `realm_can_mention_many_users_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\nChannel administrators option removed in Zulip 6.0 (feature level 133).\n\nModerators option added in Zulip 4.0 (feature level 62).\n\nNew in Zulip 4.0 (feature level 33).\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "realm_default_language": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe [organization language][org-lang] for automated messages and invitation emails.\n\n[org-lang]: /help/configure-organization-language\n" + }, + "realm_welcome_message_custom_text": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis organization's configured custom message for Welcome Bot\nto send to new user accounts, in Zulip Markdown format.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n" + }, + "realm_description": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe description of the organization, used on login and registration pages.\n" + }, + "realm_digest_emails_enabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has enabled [weekly digest emails](/help/digest-emails).\n" + }, + "realm_disallow_disposable_email_addresses": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization disallows disposable email\naddresses.\n" + }, + "realm_email_changes_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether users are allowed to change their own email address in this\norganization. This is typically disabled for organizations that\nsynchronize accounts from LDAP or a similar corporate database.\n" + }, + "realm_invite_required": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether an invitation is required to join this organization.\n" + }, + "realm_create_multiuse_invite_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to create [reusable invitation\nlinks](/help/invite-new-users#create-a-reusable-invitation-link)\nto the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 209).\n" + } + ] + }, + "realm_inline_image_preview": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization has been configured to enable\n[previews of linked images](/help/image-video-and-website-previews).\n" + }, + "realm_inline_url_embed_preview": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization has been configured to enable\n[previews of linked websites](/help/image-video-and-website-previews).\n" + }, + "realm_topics_policy": { + "type": "string", + "enum": ["allow_empty_topic", "disable_empty_topic"], + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe organization's default policy for sending channel messages to the\n[empty \"general chat\" topic](/help/require-topics).\n\n- `\"allow_empty_topic\"`: Channel messages can be sent to the empty topic.\n- `\"disable_empty_topic\"`: Channel messages cannot be sent to the empty topic.\n\n**Changes**: New in Zulip 11.0 (feature level 392). Previously, this was\ncontrolled by the boolean `realm_mandatory_topics` setting, which is now\ndeprecated.\n" + }, + "realm_mandatory_topics": { + "type": "boolean", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether [topics are required](/help/require-topics) for messages in this\norganization.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now\ncontrolled by the realm `topics_policy` setting.\n" + }, + "realm_message_retention_days": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe default [message retention policy](/help/message-retention-policy)\nfor this organization. It can have one special value:\n\n- `-1` denoting that the messages will be retained forever for this realm, by default.\n\n**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was\nencoded as `null` instead of `-1`. Clients can correctly handle all\nserver versions by treating both `-1` and `null` as indicating\nunlimited message retention.\n" + }, + "realm_name": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe name of the organization, used in login pages etc.\n" + }, + "realm_require_e2ee_push_notifications": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this realm is configured to disallow sending mobile\npush notifications with message content through the legacy\nmobile push notifications APIs. The new API uses end-to-end\nencryption to protect message content and metadata from\nbeing accessible to the push bouncer service, APNs, and\nFCM. Clients that support the new E2EE API will use it\nautomatically regardless of this setting.\n\nIf `true`, mobile push notifications sent to clients that\nlack support for E2EE push notifications will always have\n\"New message\" as their content. Note that these legacy\nmobile notifications will still contain metadata, which may\ninclude the message's ID, the sender's name, email address,\nand avatar.\n\nIn a future release, once the official mobile apps have\nimplemented fully validated their E2EE protocol support,\nthis setting will become strict, and disable the legacy\nprotocol entirely.\n\n**Changes**: New in Zulip 11.0 (feature level 409). Previously,\nthis behavior was available only via the\n`PUSH_NOTIFICATION_REDACT_CONTENT` global server setting.\n" + }, + "realm_require_unique_names": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether the organization is configured to require users\nto have unique full names. If true, the server will reject attempts\nto create a new user, or change the name of an existing user, where\ndoing so would lead to two users whose names are identical modulo\ncase and unicode normalization.\n\n**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip\nserver could not be configured to enforce unique names.\n" + }, + "realm_name_changes_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their name\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" + }, + "realm_avatar_changes_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their avatar\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" + }, + "realm_emails_restricted_to_domains": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)\nthis organization are required to have an email\naddress in one of the `realm_domains` configured for the organization.\n" + }, + "realm_send_welcome_emails": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether or not this organization is configured to send the standard Zulip\n[welcome emails](/help/disable-welcome-emails) to new users joining the organization.\n" + }, + "realm_message_content_allowed_in_email_notifications": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether notification emails in this organization are allowed to\ncontain Zulip the message content, or simply indicate that a new\nmessage was sent.\n" + }, + "realm_enable_spectator_access": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether web-public channels and related anonymous access APIs/features\nare enabled in this organization.\n\nCan only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`\n[server setting][server-settings] is enabled on the Zulip\nserver. See also the `can_create_web_public_channel_group` realm\nsetting.\n\n**Changes**: New in Zulip 5.0 (feature level 109).\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n" + }, + "realm_want_advertise_in_communities_directory": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has given permission to be advertised in the\nZulip [communities directory](/help/communities-directory).\n\nUseful only to clients supporting changing this setting for the\norganization.\n\nGiving permission via this setting does not guarantee that an\norganization will be listed in the Zulip communities directory.\n\n**Changes**: New in Zulip 6.0 (feature level 129).\n" + }, + "realm_video_chat_provider": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe configured [video call provider](/help/configure-call-provider) for the\norganization.\n\n- 0 = None\n- 1 = Jitsi Meet\n- 3 = Zoom (User OAuth integration)\n- 4 = BigBlueButton\n- 5 = Zoom (Server to Server OAuth integration)\n\nNote that only one of the [Zoom integrations][zoom-video-calls] can\nbe configured on a Zulip server.\n\n**Changes**: In Zulip 10.0 (feature level 353), added the Zoom Server\nto Server OAuth option.\n\nIn Zulip 3.0 (feature level 1), added the None option\nto disable video call UI.\n\n[zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom\n" + }, + "realm_jitsi_server_url": { + "type": "string", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the custom Jitsi Meet server configured in this organization's\nsettings.\n\n`null`, the default, means that the organization is using the should use the\nserver-level configuration, `server_jitsi_server_url`. A correct client\nsupporting only the modern API should use `realm_jitsi_server_url ||\nserver_jitsi_server_url` to create calls.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only\navailable as a server-level configuration, which was available via the\n`jitsi_server_url` field.\n" + }, + "realm_giphy_rating": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe configured GIPHY rating for the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 55).\n" + }, + "realm_waiting_period_threshold": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMembers whose accounts have been created at least this many days ago\nwill be treated as [full members][calc-full-member]\nfor the purpose of settings that restrict access to new members.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "realm_digest_weekday": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe day of the week when the organization will send\nits weekly digest email to inactive users.\n" + }, + "realm_direct_message_initiator_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to start a new direct message conversation\ninvolving other non-bot users. Users who are outside this group and attempt\nto send the first direct message to a given collection of recipient users\nwill receive an error, unless all other recipients are bots or the sender.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_direct_message_permission_group": { + "allOf": [ + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to fully use direct messages. Users outside\nthis group can only send direct messages to conversations where all the\nrecipients are in this group, are bots, or are the sender, ensuring that\nevery direct message conversation will be visible to at least one user in\nthis group.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "realm_default_code_block_language": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe default pygments language code to be used for code blocks in this\norganization. If an empty string, no default has been set.\n\n**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant\nthat both `null` and an empty string could represent that no default was\nset for this realm setting. Clients supporting older server versions\nshould treat either value (`null` or `\"\"`) as no default being set.\n" + }, + "realm_message_content_delete_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be deleted\nwith this organization's\n[message deletion policy](/help/restrict-message-editing-and-deletion).\n\nWill not be 0. A `null` value means no limit: messages can be deleted\nregardless of how long ago they were sent.\n\n**Changes**: No limit was represented using the\nspecial value `0` before Zulip 5.0 (feature level 100).\n" + }, + "realm_authentication_methods": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/RealmAuthenticationMethod" + }, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary of authentication method keys mapped to dictionaries that\ndescribe the properties of the named authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n\nClients should use this to implement server-settings UI to change which\nmethods are enabled for the organization. For authentication UI itself,\nclients should use the pre-authentication metadata returned by\n[`GET /server_settings`](/api/get-server-settings).\n\n**Changes**: In Zulip 9.0 (feature level 241), the values in this\ndictionary were changed. Previously, the values were a simple boolean\nindicating whether the backend is enabled or not.\n" + }, + "realm_allow_message_editing": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization's [message edit policy][config-message-editing]\nallows editing the content of messages.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n" + }, + "realm_message_content_edit_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be edited\nwith this organization's\n[message edit policy](/help/restrict-message-editing-and-deletion).\n\nWill not be `0`. A `null` value means no limit, so messages can be edited\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: Before Zulip 6.0 (feature level 138), no limit was\nrepresented using the special value `0`.\n" + }, + "realm_move_messages_within_stream_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be moved within a\nchannel to another topic by users who have permission to do so based on this\norganization's [topic edit policy](/help/restrict-moving-messages). This\nsetting does not affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so message topics can be\nedited regardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time\nlimit was always 72 hours for users who were not administrators or\nmoderators.\n" + }, + "realm_move_messages_between_streams_limit_seconds": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be moved between\nchannels by users who have permission to do so based on this organization's\n[message move policy](/help/restrict-moving-messages). This setting does\nnot affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so messages can be moved\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was\nno time limit for moving messages between channels for users with permission\nto do so.\n" + }, + "realm_enable_read_receipts": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether read receipts is enabled in the organization or not.\n\nIf disabled, read receipt data will be unavailable to clients, regardless\nof individual users' personal read receipt settings. See also the\n`send_read_receipts` setting within `realm_user_settings_defaults`.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n" + }, + "realm_icon_url": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's [profile icon](/help/create-your-organization-profile).\n" + }, + "realm_icon_source": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's\n[profile icon](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the organization's icon.\n\n- \"G\" means generated by Gravatar (the default).\n- \"U\" means uploaded by an organization administrator.\n" + }, + "max_icon_file_size_mib": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size allowed for the organization's\nicon. Useful for UI allowing editing the organization's icon.\n\n**Changes**: New in Zulip 5.0 (feature level 72). Previously,\nthis was called `max_icon_file_size`.\n" + }, + "realm_logo_url": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's wide logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" + }, + "realm_logo_source": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" + }, + "realm_night_logo_url": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's dark theme wide-format logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" + }, + "realm_night_logo_source": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's dark theme\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" + }, + "max_logo_file_size_mib": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size allowed for the uploaded organization logos.\n\n**Changes**: New in Zulip 5.0 (feature level 72). Previously,\nthis was called `max_logo_file_size`.\n" + }, + "realm_bot_domain": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe fake email domain that will be used for new bots created this\norganization. Useful for UI for creating bots.\n" + }, + "realm_uri": { + "type": "string", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL for the organization. Alias of `realm_url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" + }, + "realm_url": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL for the organization.\n\n**Changes**: New in Zulip 9.0 (feature level 257), replacing the\ndeprecated `realm_uri`.\n" + }, + "realm_available_video_chat_providers": { + "type": "object", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a supported [video call\nprovider](/help/configure-call-provider) that is configured on this\nserver and could be selected by an organization administrator.\n\nUseful for administrative settings UI that allows changing the realm\nsetting `video_chat_provider`.\n", + "additionalProperties": { + "description": "`{provider_name}`: Dictionary containing the details of the\nvideo call provider with the name of the chat provider as\nthe key.\n", + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The name of the video call provider.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the video call provider.\n" + } + } + } + }, + "realm_presence_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether online presence of other users is shown in this\norganization.\n" + }, + "settings_send_digest_emails": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this Zulip server is configured to allow organizations to\nenable [digest emails](/help/digest-emails).\n\nRelevant for administrative settings UI that can change the digest\nemail settings.\n" + }, + "realm_email_auth_enabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has enabled Zulip's default email and password\nauthentication feature. Determines whether Zulip stores a password\nfor the user and clients should offer any UI for changing the user's\nZulip password.\n" + }, + "realm_password_auth_enabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization allows any sort of password-based\nauthentication (whether via EmailAuthBackend or LDAP passwords).\n\nDetermines whether a client might ever need to display a password prompt\n(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)\nbefore presenting a login page).\n" + }, + "realm_push_notifications_enabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether push notifications are enabled for this organization. Typically\n`true` for Zulip Cloud and self-hosted realms that have a valid\nregistration for the [Mobile push notifications\nservice](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),\nand `false` for self-hosted servers that do not.\n\n**Changes**: Before Zulip 8.0 (feature level 231), this incorrectly was\n`true` for servers that were partly configured to use the Mobile Push\nNotifications Service but not properly registered.\n" + }, + "realm_push_notifications_enabled_end_timestamp": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nIf the server expects the realm's push notifications access to end at a\ndefinite time in the future, the UNIX timestamp (UTC) at which this is\nexpected to happen. Mobile clients should use this field to display warnings\nto users when the indicated timestamp is near.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\n" + }, + "realm_upload_quota_mib": { + "type": "integer", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe total quota for uploaded files in this organization.\n\nClients are not responsible for checking this quota; it is included\nin the API only for display purposes.\n\nIf `null`, there is no limit.\n\n**Changes**: Before Zulip 9.0 (feature level 251), this field\nwas incorrectly measured in bytes, not MiB.\n\nNew in Zulip 5.0 (feature level 72). Previously,\nthis was called `realm_upload_quota`.\n" + }, + "realm_org_type": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe [organization type](/help/organization-type) for the realm.\nUseful only to clients supporting changing this setting for the\norganization, or clients implementing onboarding content or\nother features that varies with organization type.\n\n- 0 = Unspecified\n- 10 = Business\n- 20 = Open-source project\n- 30 = Education (non-profit)\n- 35 = Education (for-profit)\n- 40 = Research\n- 50 = Event or conference\n- 60 = Non-profit (registered)\n- 70 = Government\n- 80 = Political group\n- 90 = Community\n- 100 = Personal\n- 1000 = Other\n\n**Changes**: New in Zulip 6.0 (feature level 128).\n" + }, + "realm_plan_type": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe plan type of the organization.\n\n- 1 = Self-hosted organization (SELF_HOSTED)\n- 2 = Zulip Cloud free plan (LIMITED)\n- 3 = Zulip Cloud Standard plan (STANDARD)\n- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)\n" + }, + "realm_enable_guest_user_dm_warning": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether clients should show a warning when a user is composing\na DM to a guest user in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 348).\n" + }, + "realm_enable_guest_user_indicator": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether clients should display \"(guest)\" after the names of\nguest users to prominently highlight their status.\n\n**Changes**: New in Zulip 8.0 (feature level 216).\n" + }, + "realm_can_access_all_users_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to access all users in the\norganization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 225).\n" + } + ] + }, + "realm_can_summarize_topics_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to use AI summarization.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + } + ] + }, + "zulip_plan_is_not_limited": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization is using a limited (Zulip Cloud Free) plan.\n" + }, + "upgrade_text_for_wide_organization_logo": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nText to use when displaying UI for wide organization logos, a feature\nthat is currently not available on the Zulip Cloud Free plan.\n\nUseful only for clients supporting administrative UI for uploading\na new wide organization logo to brand the organization.\n" + }, + "realm_default_external_accounts": { + "type": "object", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a default external\naccount type that can be configured with Zulip's [custom\nprofile fields feature](/help/custom-profile-fields).\n\n**Changes**: New in Zulip 2.1.0.\n", + "additionalProperties": { + "description": "`{site_name}`: Dictionary containing the details of the\ndefault external account provider with the name of the\nwebsite as the key.\n", + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The name of the external account provider\n" + }, + "text": { + "type": "string", + "description": "The text describing the external account.\n" + }, + "hint": { + "type": "string", + "description": "The help text to be displayed for the\ncustom profile field in user-facing\nsettings UI for configuring custom\nprofile fields for this account.\n" + }, + "url_pattern": { + "type": "string", + "description": "The regex pattern of the URL of a profile page\non the external site.\n" + } + } + } + }, + "jitsi_server_url": { + "type": "string", + "deprecated": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe base URL to be used to create Jitsi video calls. Equals\n`realm_jitsi_server_url || server_jitsi_server_url`.\n\n**Changes**: Deprecated in Zulip 8.0 (feature level 212) and will\neventually be removed. Previously, the Jitsi server to use was not\nconfigurable on a per-realm basis, and this field contained the server's\nconfigured Jitsi server. (Which is now provided as\n`server_jitsi_server_url`). Clients supporting older versions should fall\nback to this field when creating calls: using `realm_jitsi_server_url ||\nserver_jitsi_server_url` with newer servers and using `jitsi_server_url`\nwith servers below feature level 212.\n" + }, + "development_environment": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this Zulip server is a development environment. Used\nto control certain features or UI (such as error popups)\nthat should only apply when connected to a Zulip development\nenvironment.\n" + }, + "server_generation": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA timestamp indicating when the process hosting this\nevent queue was started. Clients will likely only find\nthis value useful for inclusion in detailed error reports.\n" + }, + "password_min_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured minimum required length for passwords.\nNecessary for password change UI to show whether the password\nwill be accepted.\n" + }, + "password_max_length": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured maximum length for passwords.\nNecessary for password change UI to show whether the password\nwill be accepted.\n\n**Changes**: New in Zulip 10.0 (feature level 338).\n" + }, + "password_min_guesses": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured minimum `zxcvbn` minimum guesses.\nNecessary for password change UI to show whether the password\nwill be accepted.\n" + }, + "giphy_rating_options": { + "type": "object", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a valid rating\nthat is configured on this server and could be selected by an\norganization administrator.\n\nUseful for administrative settings UI that allows changing the\nallowed rating of GIFs.\n", + "additionalProperties": { + "description": "`{rating_name}`: Dictionary containing the details of the\nrating with the name of the rating as\nthe key.\n", + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The description of the rating option.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the rating option.\n" + } + } + } + }, + "max_file_upload_size_mib": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size that can be uploaded to this Zulip organization.\n" + }, + "max_avatar_file_size_mib": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum avatar size that can be uploaded to this Zulip server.\n" + }, + "server_inline_image_preview": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is configured with support for inline image previews.\nClients containing administrative UI for changing\n`realm_inline_image_preview` should consult this field before offering\nthat feature.\n" + }, + "server_inline_url_embed_preview": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is configured with support for inline URL previews.\nClients containing administrative UI for changing\n`realm_inline_url_embed_preview` should consult this field before offering\nthat feature.\n" + }, + "server_thumbnail_formats": { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nA list describing the image formats that uploaded\nimages will be thumbnailed into. Any image with a\nsource starting with `/user_uploads/thumbnail/` can\nhave its last path component replaced with any of the\nnames contained in this list, to obtain the desired\nthumbnail size.\n\n**Changes**: New in Zulip 9.0 (feature level 273).\n", + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The file path component of the thumbnail format.\n" + }, + "max_width": { + "type": "integer", + "description": "The maximum width of this format.\n" + }, + "max_height": { + "type": "integer", + "description": "The maximum height of this format.\n" + }, + "format": { + "type": "string", + "description": "The extension of this format.\n" + }, + "animated": { + "type": "boolean", + "description": "If this file format is animated. These formats\nare only generated for uploaded imates which\nthemselves are animated.\n" + } + } + } + }, + "server_avatar_changes_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server allows avatar changes. Similar to\n`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`\nZulip server level setting.\n" + }, + "server_name_changes_disabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server allows name changes. Similar to\n`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`\nZulip server level setting.\n" + }, + "server_needs_upgrade": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is running an old version based on the Zulip\n[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),\nsuch that the web app will display to the current user a prominent warning.\n\n**Changes**: New in Zulip 5.0 (feature level 74).\n" + }, + "server_web_public_streams_enabled": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level\nsetting. A server that has disabled this setting intends to not offer [web\npublic channels](/help/public-access-option) to realms it hosts. (Zulip Cloud\ndefaults to `true`; self-hosted servers default to `false`).\n\nClients should use this to determine whether to offer UI for the\nrealm-level setting for enabling web-public channels\n(`realm_enable_spectator_access`).\n\n**Changes**: New in Zulip 5.0 (feature level 110).\n" + }, + "server_emoji_data_url": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL to a JSON file that describes which emoji names map to which\nemoji codes, for all Unicode emoji this Zulip server accepts.\n\nThe data at the given URL is a JSON object with one property, `code_to_names`.\nThe value of that property is a JSON object where each key is an\n[emoji code](/api/add-reaction#parameter-emoji_code) for an available\nUnicode emoji, and each value is the corresponding\n[emoji names](/api/add-reaction#parameter-emoji_name) for this emoji,\nwith the canonical name for the emoji always appearing first.\n\nThe HTTP response at that URL will have appropriate HTTP caching headers, such\nany HTTP implementation should get a cached version if emoji haven't changed\nsince the last request.\n\n**Changes**: New in Zulip 6.0 (feature level 140).\n" + }, + "server_jitsi_server_url": { + "type": "string", + "nullable": true, + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the Jitsi server that the Zulip server is configured to use by\ndefault; the organization-level setting `realm_jitsi_server_url` takes\nprecedence over this setting when both are set.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this value\nwas available as the now-deprecated `jitsi_server_url`.\n" + }, + "server_can_summarize_topics": { + "type": "boolean", + "description": "Present if `realm` is present in `fetch_event_types`\n\nWhether topic summarization is enabled in the server or\nnot depending upon whether `TOPIC_SUMMARIZATION_MODEL`\nis set or not.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + }, + "event_queue_longpoll_timeout_seconds": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nRecommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.\nThis is guaranteed to be somewhat greater than the heartbeat frequency. It is important\nthat clients respect this parameter, so that increases in the heartbeat frequency do not\nbreak clients.\n\n**Changes**: New in Zulip 5.0 (feature level 74). Previously,\nthis was hardcoded to 90 seconds, and clients should use that as a fallback\nvalue when interacting with servers where this field is not present.\n" + }, + "realm_billing": { + "type": "object", + "additionalProperties": false, + "description": "Present if `realm_billing` is present in `fetch_event_types`.\n\nA dictionary containing billing information of the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363).\n", + "properties": { + "has_pending_sponsorship_request": { + "type": "boolean", + "description": "Whether there is a pending sponsorship request for the organization. Note that\nthis field will always be `false` if the user is not in `can_manage_billing_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 363).\n" + } + } + }, + "realm_moderation_request_channel_id": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the private channel to which messages flagged by users for\nmoderation are sent. Moderators can use this channel to review and\nact on reported content.\n\nWill be `-1` if moderation requests are disabled.\n\nClients should check whether moderation requests are disabled to\ndetermine whether to present a \"report message\" feature in their UI\nwithin a given organization.\n\n**Changes**: New in Zulip 10.0 (feature level 331). Previously,\nno \"report message\" feature existed in Zulip.\n" + }, + "realm_new_stream_announcements_stream_id": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing the\n[creation of new channels][new-channel-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed 'realm_notifications_stream_id'\nto `realm_new_stream_announcements_stream_id`.\n" + }, + "realm_signup_announcements_stream_id": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing\nthat [new users have joined the organization][new-user-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-user-announce]: /help/configure-automated-notices#new-user-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed\n'realm_signup_notifications_stream_id' to `realm_signup_announcements_stream_id`.\n" + }, + "realm_zulip_update_announcements_stream_id": { + "type": "integer", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing\nnew features or other end-user updates about the Zulip software are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n**Changes**: New in Zulip 9.0 (feature level 242).\n" + }, + "realm_empty_topic_display_name": { + "type": "string", + "description": "Present if `realm` is present in `fetch_event_types`.\n\nClients declaring the `empty_topic_name` client capability\nshould use the value of `realm_empty_topic_display_name` to\ndetermine how to display the empty string topic.\n\nClients not declaring the `empty_topic_name` client capability\nreceive `realm_empty_topic_display_name` value as the topic name\nreplacing empty string.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously,\nthe empty string was not a valid topic name.\n" + }, + "realm_user_settings_defaults": { + "type": "object", + "additionalProperties": false, + "description": "Present if `realm_user_settings_defaults` is present in `fetch_event_types`.\n\nA dictionary containing the default values of settings for new users.\n\n**Changes**: New in Zulip 5.0 (feature level 95).\n", + "properties": { + "twenty_four_hour_time": { + "type": "boolean", + "nullable": true, + "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\nA `null` value indicates that the client should use the default time\nformat for the user's locale.\n\n**Changes**: Prior to Zulip 11.0 (feature level 408), `null`\nwas not a valid value for this setting. Note that it was not possible\nto actually set the time format to `null` at this feature level.\n\nNew in Zulip 5.0 (feature level 99). This value was previously\navailable as `realm_default_twenty_four_hour_time` in the top-level\nresponse object (only when `realm` was present in\n`fetch_event_types`).\n" + }, + "web_mark_read_on_scroll_policy": { + "type": "integer", + "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n" + }, + "web_channel_default_view": { + "type": "integer", + "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nIn Zulip 11.0 (feature level 383), we added a new option \"List of topics\"\nto this setting.\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n" + }, + "starred_message_counts": { + "type": "boolean", + "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n" + }, + "receives_typing_notifications": { + "type": "boolean", + "description": "Whether the user is configured to receive typing notifications from\nother users. The server will only deliver typing notifications events\nto users who for whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" + }, + "web_suggest_update_timezone": { + "type": "boolean", + "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n" + }, + "fluid_layout_width": { + "type": "boolean", + "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n" + }, + "high_contrast_mode": { + "type": "boolean", + "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n" + }, + "web_font_size_px": { + "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", + "type": "integer", + "example": 14 + }, + "web_line_height_percent": { + "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", + "type": "integer", + "example": 122 + }, + "color_scheme": { + "type": "integer", + "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n" + }, + "translate_emoticons": { + "type": "boolean", + "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n" + }, + "display_emoji_reaction_users": { + "type": "boolean", + "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting\nusers, rather than a count, for messages with few total\nreactions. The ideal cutoff may depend on the space\navailable for displaying reactions; the official web\napplication displays names when 3 or fewer total reactions\nare present with this setting enabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n" + }, + "default_language": { + "type": "string", + "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n" + }, + "web_home_view": { + "type": "string", + "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n" + }, + "web_escape_navigates_to_home_view": { + "type": "boolean", + "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n" + }, + "left_side_userlist": { + "type": "boolean", + "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n" + }, + "emojiset": { + "type": "string", + "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n" + }, + "demote_inactive_streams": { + "type": "integer", + "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n" + }, + "user_list_style": { + "type": "integer", + "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n" + }, + "web_animate_image_previews": { + "type": "string", + "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n" + }, + "web_stream_unreads_count_display_policy": { + "type": "integer", + "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n" + }, + "hide_ai_features": { + "type": "boolean", + "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + }, + "web_left_sidebar_show_channel_folders": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n" + }, + "web_left_sidebar_unreads_count_summary": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n" + }, + "enable_stream_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for channel messages.\n" + }, + "enable_stream_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for channel messages.\n" + }, + "enable_stream_push_notifications": { + "type": "boolean", + "description": "Enable mobile notifications for channel messages.\n" + }, + "enable_stream_audible_notifications": { + "type": "boolean", + "description": "Enable audible desktop notifications for channel messages.\n" + }, + "notification_sound": { + "type": "string", + "description": "Notification sound name.\n" + }, + "enable_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for direct messages and @-mentions.\n" + }, + "enable_sounds": { + "type": "boolean", + "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n" + }, + "enable_offline_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n" + }, + "enable_offline_push_notifications": { + "type": "boolean", + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n" + }, + "enable_online_push_notifications": { + "type": "boolean", + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n" + }, + "enable_followed_topic_desktop_notifications": { + "type": "boolean", + "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_email_notifications": { + "type": "boolean", + "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_push_notifications": { + "type": "boolean", + "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_followed_topic_audible_notifications": { + "type": "boolean", + "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "enable_digest_emails": { + "type": "boolean", + "description": "Enable digest emails when the user is away.\n" + }, + "enable_marketing_emails": { + "type": "boolean", + "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n" + }, + "enable_login_emails": { + "type": "boolean", + "description": "Enable email notifications for new logins to account.\n" + }, + "message_content_in_email_notifications": { + "type": "boolean", + "description": "Include the message's content in email notifications for new messages.\n" + }, + "pm_content_in_desktop_notifications": { + "type": "boolean", + "description": "Include content of direct messages in desktop notifications.\n" + }, + "wildcard_mentions_notify": { + "type": "boolean", + "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n" + }, + "enable_followed_topic_wildcard_mentions_notify": { + "type": "boolean", + "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" + }, + "desktop_icon_count_display": { + "type": "integer", + "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,\nand followed topics` option, renumbering the options to insert it in\norder.\n" + }, + "realm_name_in_email_notifications_policy": { + "type": "integer", + "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n" + }, + "automatically_follow_topics_policy": { + "type": "integer", + "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "type": "integer", + "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" + }, + "automatically_follow_topics_where_mentioned": { + "type": "boolean", + "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n" + }, + "resolved_topic_notice_auto_read_policy": { + "type": "string", + "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n" + }, + "presence_enabled": { + "type": "boolean", + "description": "Display the presence status to other users when online.\n" + }, + "enter_sends": { + "type": "boolean", + "description": "Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)\nin the compose box is enabled.\n" + }, + "enable_drafts_synchronization": { + "type": "boolean", + "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n" + }, + "email_notifications_batching_period_seconds": { + "type": "integer", + "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n" + }, + "available_notification_sounds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Array containing the names of the notification sound options\nsupported by this Zulip server. Only relevant to support UI\nfor configuring notification sounds.\n" + }, + "emojiset_choices": { + "description": "Array of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n", + "type": "array", + "items": { + "type": "object", + "description": "Object describing a emoji set.\n", + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" + }, + "text": { + "type": "string", + "description": "The text describing the emoji set.\n" + } + } + } + }, + "send_private_typing_notifications": { + "type": "boolean", + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "send_stream_typing_notifications": { + "type": "boolean", + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "send_read_receipts": { + "type": "boolean", + "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" + }, + "allow_private_data_export": { + "type": "boolean", + "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n" + }, + "email_address_visibility": { + "$ref": "#/components/schemas/EmailAddressVisibility" + }, + "web_navigate_to_sent_message": { + "type": "boolean", + "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n" + } + } + }, + "realm_users": { + "type": "array", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nA array of dictionaries where each entry describes a user\nwhose account has not been deactivated. Note that unlike\nthe usual User dictionary, this does not contain the `is_active`\nkey, as all the users present in this array have active accounts.\n\nIf the current user is a guest whose access to users is limited by a\n`can_access_all_users_group` policy, and the event queue was registered\nwith the `user_list_incomplete` client capability, then users that the\ncurrent user cannot access will not be included in this array. If the\ncurrent user's access to a user is restricted but the client lacks this\ncapability, then that inaccessible user will appear in the users array as\nan \"Unknown user\" object with the usual format but placeholder data whose\nonly variable content is the user ID.\n\nSee also `cross_realm_bots` and `realm_non_active_users`.\n\n**Changes**: Before Zulip 8.0 (feature level 232), the\n`user_list_incomplete` client capability did not exist, and so all\nclients whose access to a new user was prevented by\n`can_access_all_users_group` policy would receive a fake \"Unknown\nuser\" event for such users.\n", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "realm_non_active_users": { + "type": "array", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nA array of dictionaries where each entry describes a user\nwhose account has been deactivated. Note that unlike\nthe usual User dictionary this does not contain the `is_active`\nkey as all the users present in this array have deactivated\naccounts.\n", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "avatar_source": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe avatar data source type for the current user.\n\nValue values are `G` (gravatar) and `U` (uploaded by user).\n" + }, + "avatar_url_medium": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe avatar URL for the current user at 500x500 resolution, appropriate\nfor use in settings UI showing the user's avatar.\n" + }, + "avatar_url": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe URL of the avatar for the current user at 100x100\nresolution. See also `avatar_url_medium`.\n" + }, + "can_create_streams": { + "type": "boolean", + "deprecated": true, + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create at least one type\nof channel with the organization's [channel creation\npolicy](/help/configure-who-can-create-channels). Its value will\nalways equal `can_create_public_streams || can_create_private_streams`.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 102), when\nthe new `create_private_stream_policy` and\n`create_public_stream_policy` properties introduced the\npossibility that a user could only create one type of channel.\n\nThis field will be removed in a future release.\n" + }, + "can_create_public_streams": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create public channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\n**Changes**: New in Zulip 5.0 (feature level 102). In older\nversions, the deprecated `can_create_streams` property should be\nused to determine whether the user can create public channels.\n" + }, + "can_create_private_streams": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create private channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\n**Changes**: New in Zulip 5.0 (feature level 102). In older\nversions, the deprecated `can_create_streams` property should be\nused to determine whether the user can create private channels.\n" + }, + "can_create_web_public_streams": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create public channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\nNote that this will be false if the Zulip server does not have the\n`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has\nnot enabled the `enable_spectator_access` realm setting.\n\n**Changes**: New in Zulip 5.0 (feature level 103).\n" + }, + "can_subscribe_other_users": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to subscribe other users to channels with\nthe organization's [channels policy](/help/configure-who-can-invite-to-channels).\n" + }, + "can_invite_others_to_realm": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user [is allowed to invite others][who-can-send-invitations]\nto the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 51).\n\n[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations\n" + }, + "is_admin": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is at least an [organization administrator](/api/roles-and-permissions).\n" + }, + "is_owner": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is an [organization owner](/api/roles-and-permissions).\n\n**Changes**: New in Zulip 3.0 (feature level 11).\n" + }, + "is_moderator": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is at least an [organization moderator](/api/roles-and-permissions).\n\n**Changes**: Prior to Zulip 11.0 (feature level 380), this was only true\nfor users whose role was exactly the moderator role.\n\nNew in Zulip 4.0 (feature level 60).\n" + }, + "is_guest": { + "type": "boolean", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is a [guest user](/api/roles-and-permissions).\n" + }, + "user_id": { + "type": "integer", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe unique ID for the current user.\n" + }, + "email": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe Zulip API email address for the current user. See also\n`delivery_email`; these may be the same or different depending\non the user's `email_address_visibility` policy.\n" + }, + "delivery_email": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe user's email address, appropriate for UI for changing\nthe user's email address. See also `email`.\n" + }, + "full_name": { + "type": "string", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe full name of the current user.\n" + }, + "cross_realm_bots": { + "type": "array", + "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nArray of dictionaries where each dictionary contains details of\na single cross realm bot. Cross-realm bots are special system bot accounts\nlike Notification Bot.\n\nMost clients will want to combine this with `realm_users` in many\ncontexts.\n", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/UserBase" + }, + { + "additionalProperties": false, + "properties": { + "user_id": {}, + "delivery_email": {}, + "email": {}, + "full_name": {}, + "date_joined": {}, + "is_active": {}, + "is_owner": {}, + "is_admin": {}, + "is_guest": {}, + "is_bot": {}, + "is_system_bot": { + "type": "boolean", + "description": "Whether the user is a system bot. System bots are special\nbot user accounts that are managed by the system, rather than\nthe organization's administrators.\n\n**Changes**: This field was called `is_cross_realm_bot`\nbefore Zulip 5.0 (feature level 83).\n" + }, + "bot_type": { + "nullable": true + }, + "bot_owner_id": { + "nullable": true + }, + "role": {}, + "timezone": {}, + "avatar_url": { + "nullable": true + }, + "avatar_version": {}, + "profile_data": {} + } + } + ] + } + }, + "server_supported_permission_settings": { + "description": "Present if `realm` is present in `fetch_event_types`.\n\nMetadata detailing the valid values for permission settings that\nuse [group-setting values](/api/group-setting-values). Clients\nshould use these data as explained in the\n[main documentation](/api/group-setting-values#permitted-values)\nto determine what values to present as possible values for these\nsettings in UI components.\n\n**Changes**: Before Zulip 10.0 (feature level 326), this part of\nthe response had a documented-as-unstable format not suitable\nfor general client use, and should be ignored.\n\nNew in Zulip 8.0 (feature level 221).\n", + "type": "object", + "additionalProperties": false, + "properties": { + "realm": { + "type": "object", + "description": "Configuration for realm level group permission settings.\n", + "additionalProperties": { + "$ref": "#/components/schemas/GroupPermissionSetting" + } + }, + "stream": { + "type": "object", + "description": "Configuration for channel level group permission settings.\n", + "additionalProperties": { + "$ref": "#/components/schemas/GroupPermissionSetting" + } + }, + "group": { + "type": "object", + "description": "Configuration for group level group permission settings.\n", + "additionalProperties": { + "$ref": "#/components/schemas/GroupPermissionSetting" + } + } + } + }, + "max_bulk_new_subscription_messages": { + "description": "Maximum number of new subscribers for which the server will\nrespect the `send_new_subscription_messages` parameter when\n[adding subscribers to a channel](/api/subscribe#parameter-send_new_subscription_messages).\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n", + "type": "number", + "example": 100 + } + }, + "example": { + "last_event_id": -1, + "msg": "", + "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", + "realm_emoji": { + "1": { + "author_id": 5, + "deactivated": false, + "id": "1", + "name": "green_tick", + "source_url": "/user_avatars/1/emoji/images/1.png" + }, + "2": { + "author_id": 3, + "deactivated": false, + "id": "2", + "name": "animated_img", + "source_url": "/user_avatars/1/emoji/images/animated_img.gif", + "still_url": "/user_avatars/1/emoji/images/still/animated_img.png" + } + }, + "result": "success", + "zulip_feature_level": 2, + "zulip_version": "5.0-dev-1650-gc3fd37755f", + "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c" + } + } + ] + } + } + } + } + } + } + }, + "/server_settings": { + "get": { + "operationId": "get-server-settings", + "summary": "Get server settings", + "tags": ["server_and_organizations"], + "x-response-description": "Please note that not all of these attributes are guaranteed to appear in a\nresponse, for two reasons:\n\n* This endpoint has evolved over time, so responses from older Zulip servers\n might be missing some keys (in which case a client should assume the\n appropriate default).\n* If a `/server_settings` request is made to the root domain of a\n multi-subdomain server, like the root domain of zulip.com, the settings\n that are realm-specific are not known and thus not provided.\n", + "description": "Fetch global settings for a Zulip server.\n\n**Note:** this endpoint does not require any authentication at all, and you can use it to check:\n\n- If this is a Zulip server, and if so, what version of Zulip it's running.\n- What a Zulip client (e.g. a mobile app or\n [zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to\n know in order to display a login prompt for the server (e.g. what\n authentication methods are available).\n", + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "authentication_methods": { + "type": "object", + "additionalProperties": false, + "deprecated": true, + "description": "Each key-value pair in the object indicates whether the authentication\nmethod is enabled on this server.\n\n**Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive\n`external_authentication_methods`.\n", + "properties": { + "password": { + "description": "Whether the user can authenticate using password.\n", + "type": "boolean" + }, + "dev": { + "description": "Whether the user can authenticate using development API key.\n", + "type": "boolean" + }, + "email": { + "description": "Whether the user can authenticate using email.\n", + "type": "boolean" + }, + "ldap": { + "description": "Whether the user can authenticate using LDAP.\n", + "type": "boolean" + }, + "remoteuser": { + "description": "Whether the user can authenticate using REMOTE_USER.\n", + "type": "boolean" + }, + "github": { + "description": "Whether the user can authenticate using their GitHub account.\n", + "type": "boolean" + }, + "azuread": { + "description": "Whether the user can authenticate using their Microsoft Entra ID account.\n", + "type": "boolean" + }, + "gitlab": { + "description": "Whether the user can authenticate using their GitLab account.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", + "type": "boolean" + }, + "apple": { + "description": "Whether the user can authenticate using their Apple account.\n", + "type": "boolean" + }, + "google": { + "description": "Whether the user can authenticate using their Google account.\n", + "type": "boolean" + }, + "saml": { + "description": "Whether the user can authenticate using SAML.\n", + "type": "boolean" + }, + "openid connect": { + "description": "Whether the user can authenticate using OpenID Connect.\n", + "type": "boolean" + } + } + }, + "external_authentication_methods": { + "type": "array", + "description": "A list of dictionaries describing the available external\nauthentication methods (E.g. Google, GitHub, or SAML)\nenabled for this organization.\n\nThe list is sorted in the order in which these\nauthentication methods should be displayed.\n\n**Changes**: New in Zulip 2.1.0.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "A unique, table, machine-readable name for the authentication method,\nintended to be used by clients with special behavior for specific\nauthentication methods to correctly identify the method.\n" + }, + "display_name": { + "type": "string", + "description": "Display name of the authentication method, to be used in all buttons\nfor the authentication method.\n" + }, + "display_icon": { + "type": "string", + "nullable": true, + "description": "URL for an image to be displayed as an icon in all buttons for\nthe external authentication method.\n\nWhen `null`, no icon should be displayed.\n" + }, + "login_url": { + "type": "string", + "description": "URL to be used to initiate authentication using this method.\n" + }, + "signup_url": { + "type": "string", + "description": "URL to be used to initiate account registration using this method.\n" + } + } + } + }, + "zulip_feature_level": { + "type": "integer", + "description": "An integer indicating what features are\navailable on the server. The feature level increases monotonically;\na value of N means the server supports all API features introduced\nbefore feature level N. This is designed to provide a simple way\nfor client apps to decide whether the server supports a given\nfeature or API change. See the [changelog](/api/changelog) for\ndetails on what each feature level means.\n\n**Changes**: New in Zulip 3.0 (feature level 1). We recommend using an\nimplied value of 0 for Zulip servers that do not send this field.\n" + }, + "zulip_version": { + "type": "string", + "description": "The server's version number. This is often a release version number,\nlike `2.1.7`. But for a server running a [version from Git][git-release],\nit will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.\n\n[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions\n" + }, + "zulip_merge_base": { + "type": "string", + "description": "The `git merge-base` between `zulip_version` and official branches\nin the public\n[Zulip server and web app repository](https://github.com/zulip/zulip),\nin the same format as `zulip_version`. This will equal\n`zulip_version` if the server is not running a fork of the Zulip server.\n\nThis will be `\"\"` if unavailable.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" + }, + "push_notifications_enabled": { + "type": "boolean", + "description": "Whether mobile/push notifications are configured.\n" + }, + "is_incompatible": { + "type": "boolean", + "description": "Whether the Zulip client that has sent a request to this endpoint is\ndeemed incompatible with the server.\n" + }, + "email_auth_enabled": { + "type": "boolean", + "description": "Setting for allowing users authenticate with an email-password\ncombination.\n" + }, + "require_email_format_usernames": { + "type": "boolean", + "description": "Whether all valid usernames for authentication to this\norganization will be email addresses. This is important\nfor clients to know whether to do client side validation\nof email address format in a login prompt.\n\nThis value will be false if the server has [LDAP\nauthentication][ldap-auth] enabled with a username and\npassword combination.\n\n[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory\n" + }, + "realm_uri": { + "type": "string", + "deprecated": true, + "description": "The organization's canonical URL. Alias of `realm_url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" + }, + "realm_url": { + "type": "string", + "description": "The organization's canonical URL.\n\n**Changes**: New in Zulip 9.0 (feature level 257), replacing the\ndeprecated `realm_uri`.\n" + }, + "realm_name": { + "type": "string", + "description": "The organization's name (for display purposes).\n" + }, + "realm_icon": { + "type": "string", + "description": "The URL for the organization's logo formatted as a square image,\nused for identifying the organization in small locations in the\nmobile and desktop apps.\n" + }, + "realm_description": { + "type": "string", + "description": "HTML description of the organization, as configured by the [organization\nprofile](/help/create-your-organization-profile).\n" + }, + "realm_web_public_access_enabled": { + "type": "boolean", + "description": "Whether the organization has enabled the creation of\n[web-public channels](/help/public-access-option) and\nat least one web-public channel on the server currently\nexists. Clients that support viewing content\nin web-public channels without an account can\nuse this to determine whether to offer that\nfeature on the login page for an organization.\n\n**Changes**: New in Zulip 5.0 (feature level 116).\n" + } + }, + "example": { + "authentication_methods": { + "password": true, + "dev": true, + "email": true, + "ldap": false, + "remoteuser": false, + "github": true, + "azuread": false, + "google": true, + "saml": true + }, + "zulip_version": "5.0-dev-1650-gc3fd37755f", + "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c", + "push_notifications_enabled": false, + "msg": "", + "is_incompatible": false, + "email_auth_enabled": true, + "require_email_format_usernames": true, + "realm_uri": "http://localhost:9991", + "realm_url": "http://localhost:9991", + "realm_name": "Zulip Dev", + "realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon", + "realm_description": "

The Zulip development environment default organization. It's great for testing!

", + "realm_web_public_access_enabled": false, + "result": "success", + "external_authentication_methods": [ + { + "name": "saml:idp_name", + "display_name": "SAML", + "display_icon": null, + "login_url": "/accounts/login/social/saml/idp_name", + "signup_url": "/accounts/register/social/saml/idp_name" + }, + { + "name": "google", + "display_name": "Google", + "display_icon": "/static/images/authentication_backends/googl_e-icon.png", + "login_url": "/accounts/login/social/google", + "signup_url": "/accounts/register/social/google" + }, + { + "name": "github", + "display_name": "GitHub", + "display_icon": "/static/images/authentication_backends/github-icon.png", + "login_url": "/accounts/login/social/github", + "signup_url": "/accounts/register/social/github" + } + ] + } + } + ] + } + } + } + } + } + } + }, + "/settings": { + "patch": { + "operationId": "update-settings", + "summary": "Update settings", + "tags": ["users"], + "description": "This endpoint is used to edit the current user's settings.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0\n(feature level 364) as we now have `web_font_size_px` and\n`web_line_height_percent` settings for more control.\n\nPrior to Zulip 5.0 (feature level 80), this endpoint only\nsupported the `full_name`, `email`, `old_password`, and\n`new_password` parameters. Notification settings were\nmanaged by `PATCH /settings/notifications`, and all other\nsettings by `PATCH /settings/display`.\n\nThe feature level 80 migration to merge these endpoints did not\nchange how request parameters are encoded. However, it did change\nthe handling of any invalid parameters present in a request\n(see feature level 78 change below).\n\nAs of feature level 80, the `PATCH /settings/display` and\n`PATCH /settings/notifications` endpoints are deprecated aliases\nfor this endpoint for backwards-compatibility, and will be removed\nonce clients have migrated to use this endpoint.\n\nPrior to Zulip 5.0 (feature level 78), this endpoint indicated\nwhich parameters it had processed by including in the response\nobject `\"key\": value` entries for values successfully changed by\nthe request. That was replaced by the more ergonomic\n[`ignored_parameters_unsupported`][ignored-parameters] array.\n\nThe `PATCH /settings/notifications` and `PATCH /settings/display`\nendpoints also had this behavior of indicating processed parameters\nbefore they became aliases of this endpoint in Zulip 5.0 (see\nfeature level 80 change above).\n\nBefore feature level 78, request parameters that were not supported\n(or were unchanged) were silently ignored.\n\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["left_side_userlist", "emojiset"] + } + } + ] + }, + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "full_name": { + "description": "A new display name for the user.\n", + "type": "string", + "example": "NewName" + }, + "email": { + "description": "Asks the server to initiate a confirmation sequence to change the user's email\naddress to the indicated value. The user will need to demonstrate control of the\nnew email address by clicking a confirmation link sent to that address.\n", + "type": "string", + "example": "newname@example.com" + }, + "old_password": { + "description": "The user's old Zulip password (or LDAP password, if LDAP authentication is in use).\n\nRequired only when sending the `new_password` parameter.\n", + "type": "string", + "example": "old12345" + }, + "new_password": { + "description": "The user's new Zulip password (or LDAP password, if LDAP authentication is in use).\n\nThe `old_password` parameter must be included in the request.\n", + "type": "string", + "example": "new12345" + }, + "twenty_four_hour_time": { + "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "web_mark_read_on_scroll_policy": { + "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "web_channel_default_view": { + "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n", + "type": "integer", + "enum": [1, 2, 4], + "example": 1 + }, + "starred_message_counts": { + "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "receives_typing_notifications": { + "description": "Whether the user is configured to receive typing notifications from other users.\nThe server will only deliver typing notifications events to users who for whom this\nis enabled.\n\nBy default, this is set to true, enabling user to receive typing\nnotifications from other users.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only\noptions to disable sending typing notifications.\n", + "type": "boolean", + "example": true + }, + "web_suggest_update_timezone": { + "type": "boolean", + "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n", + "example": true + }, + "fluid_layout_width": { + "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "high_contrast_mode": { + "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "web_font_size_px": { + "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", + "type": "integer", + "example": 14 + }, + "web_line_height_percent": { + "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", + "type": "integer", + "example": 122 + }, + "color_scheme": { + "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "enable_drafts_synchronization": { + "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n\n**Changes**: New in Zulip 5.0 (feature level 87).\n", + "type": "boolean", + "example": true + }, + "translate_emoticons": { + "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "display_emoji_reaction_users": { + "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting users, rather than\na count, for messages with few total reactions. The ideal cutoff may depend on\nthe space available for displaying reactions; the official web application\ndisplays names when 3 or fewer total reactions are present with this setting\nenabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n", + "type": "boolean", + "example": false + }, + "default_language": { + "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).\n", + "type": "string", + "example": "en" + }, + "web_home_view": { + "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n\nBefore Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", + "type": "string", + "example": "all_messages" + }, + "web_escape_navigates_to_home_view": { + "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n", + "type": "boolean", + "example": true + }, + "left_side_userlist": { + "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "boolean", + "example": true + }, + "emojiset": { + "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", + "type": "string", + "example": "google" + }, + "demote_inactive_streams": { + "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "user_list_style": { + "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "web_animate_image_previews": { + "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n", + "type": "string", + "enum": ["always", "on_hover", "never"], + "example": "on_hover" + }, + "web_stream_unreads_count_display_policy": { + "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 2 + }, + "hide_ai_features": { + "type": "boolean", + "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" + }, + "web_left_sidebar_show_channel_folders": { + "type": "boolean", + "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n", + "example": true + }, + "web_left_sidebar_unreads_count_summary": { + "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n", + "type": "boolean", + "example": true + }, + "timezone": { + "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", + "type": "string", + "example": "Asia/Kolkata" + }, + "enable_stream_desktop_notifications": { + "description": "Enable visual desktop notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_stream_email_notifications": { + "description": "Enable email notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_stream_push_notifications": { + "description": "Enable mobile notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_stream_audible_notifications": { + "description": "Enable audible desktop notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "notification_sound": { + "description": "Notification sound name.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).\n", + "type": "string", + "example": "ding" + }, + "enable_desktop_notifications": { + "description": "Enable visual desktop notifications for direct messages and @-mentions.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_sounds": { + "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "email_notifications_batching_period_seconds": { + "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n\n**Changes**: New in Zulip 5.0 (feature level 82)\n", + "type": "integer", + "example": 120 + }, + "enable_offline_email_notifications": { + "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_offline_push_notifications": { + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_online_push_notifications": { + "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_desktop_notifications": { + "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_email_notifications": { + "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_push_notifications": { + "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": false + }, + "enable_followed_topic_audible_notifications": { + "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": false + }, + "enable_digest_emails": { + "description": "Enable digest emails when the user is away.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_marketing_emails": { + "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_login_emails": { + "description": "Enable email notifications for new logins to account.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "message_content_in_email_notifications": { + "description": "Include the message's content in email notifications for new messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "pm_content_in_desktop_notifications": { + "description": "Include content of direct messages in desktop notifications.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "wildcard_mentions_notify": { + "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enable_followed_topic_wildcard_mentions_notify": { + "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", + "type": "boolean", + "example": true + }, + "desktop_icon_count_display": { + "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed\ntopics` option, renumbering the options to insert it in order.\n\nBefore Zulip 5.0 (feature level 80), this setting was managed by the\n`PATCH /settings/notifications` endpoint.\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "realm_name_in_email_notifications_policy": { + "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n\nBefore Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications`\nsetting was managed by the `PATCH /settings/notifications` endpoint.\n", + "type": "integer", + "enum": [1, 2, 3], + "example": 1 + }, + "automatically_follow_topics_policy": { + "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", + "type": "integer", + "enum": [1, 2, 3, 4], + "example": 1 + }, + "automatically_follow_topics_where_mentioned": { + "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n", + "type": "boolean", + "example": true + }, + "resolved_topic_notice_auto_read_policy": { + "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n", + "type": "string", + "enum": ["always", "except_followed", "never"], + "example": "except_followed" + }, + "presence_enabled": { + "description": "Display the presence status to other users when online.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", + "type": "boolean", + "example": true + }, + "enter_sends": { + "description": "Whether pressing Enter in the compose box sends a message\n(or saves a message edit).\n\n**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by\nthe `POST /users/me/enter-sends` endpoint, with the same parameter format.\n", + "type": "boolean", + "example": true + }, + "send_private_typing_notifications": { + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "send_stream_typing_notifications": { + "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "send_read_receipts": { + "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", + "type": "boolean", + "example": true + }, + "allow_private_data_export": { + "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n", + "type": "boolean", + "example": true + }, + "email_address_visibility": { + "description": "The [policy][permission-level] this user has selected for [which other\nusers][help-email-visibility] in this organization can see their real\nemail address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n", + "type": "integer", + "enum": [1, 2, 3, 4, 5], + "example": 1 + }, + "web_navigate_to_sent_message": { + "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n", + "type": "boolean", + "example": true + } + } + }, + "encoding": { + "twenty_four_hour_time": { + "contentType": "application/json" + }, + "web_mark_read_on_scroll_policy": { + "contentType": "application/json" + }, + "web_channel_default_view": { + "contentType": "application/json" + }, + "starred_message_counts": { + "contentType": "application/json" + }, + "receives_typing_notifications": { + "contentType": "application/json" + }, + "web_suggest_update_timezone": { + "contentType": "application/json" + }, + "fluid_layout_width": { + "contentType": "application/json" + }, + "high_contrast_mode": { + "contentType": "application/json" + }, + "web_font_size_px": { + "contentType": "application/json" + }, + "web_line_height_percent": { + "contentType": "application/json" + }, + "color_scheme": { + "contentType": "application/json" + }, + "enable_drafts_synchronization": { + "contentType": "application/json" + }, + "translate_emoticons": { + "contentType": "application/json" + }, + "display_emoji_reaction_users": { + "contentType": "application/json" + }, + "web_escape_navigates_to_home_view": { + "contentType": "application/json" + }, + "left_side_userlist": { + "contentType": "application/json" + }, + "demote_inactive_streams": { + "contentType": "application/json" + }, + "user_list_style": { + "contentType": "application/json" + }, + "web_stream_unreads_count_display_policy": { + "contentType": "application/json" + }, + "hide_ai_features": { + "contentType": "application/json" + }, + "web_left_sidebar_show_channel_folders": { + "contentType": "application/json" + }, + "web_left_sidebar_unreads_count_summary": { + "contentType": "application/json" + }, + "enable_stream_desktop_notifications": { + "contentType": "application/json" + }, + "enable_stream_email_notifications": { + "contentType": "application/json" + }, + "enable_stream_push_notifications": { + "contentType": "application/json" + }, + "enable_stream_audible_notifications": { + "contentType": "application/json" + }, + "enable_desktop_notifications": { + "contentType": "application/json" + }, + "enable_sounds": { + "contentType": "application/json" + }, + "email_notifications_batching_period_seconds": { + "contentType": "application/json" + }, + "enable_offline_email_notifications": { + "contentType": "application/json" + }, + "enable_offline_push_notifications": { + "contentType": "application/json" + }, + "enable_online_push_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_desktop_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_email_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_push_notifications": { + "contentType": "application/json" + }, + "enable_followed_topic_audible_notifications": { + "contentType": "application/json" + }, + "enable_digest_emails": { + "contentType": "application/json" + }, + "enable_marketing_emails": { + "contentType": "application/json" + }, + "enable_login_emails": { + "contentType": "application/json" + }, + "message_content_in_email_notifications": { + "contentType": "application/json" + }, + "pm_content_in_desktop_notifications": { + "contentType": "application/json" + }, + "wildcard_mentions_notify": { + "contentType": "application/json" + }, + "enable_followed_topic_wildcard_mentions_notify": { + "contentType": "application/json" + }, + "desktop_icon_count_display": { + "contentType": "application/json" + }, + "realm_name_in_email_notifications_policy": { + "contentType": "application/json" + }, + "automatically_follow_topics_policy": { + "contentType": "application/json" + }, + "automatically_unmute_topics_in_muted_streams_policy": { + "contentType": "application/json" + }, + "automatically_follow_topics_where_mentioned": { + "contentType": "application/json" + }, + "presence_enabled": { + "contentType": "application/json" + }, + "enter_sends": { + "contentType": "application/json" + }, + "send_private_typing_notifications": { + "contentType": "application/json" + }, + "send_stream_typing_notifications": { + "contentType": "application/json" + }, + "send_read_receipts": { + "contentType": "application/json" + }, + "allow_private_data_export": { + "contentType": "application/json" + }, + "email_address_visibility": { + "contentType": "application/json" + }, + "web_navigate_to_sent_message": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessIgnoredParameters" + } + } + } + }, + "/streams/{stream_id}/members": { + "get": { + "operationId": "get-subscribers", + "summary": "Get channel subscribers", + "tags": ["channels"], + "description": "Get all users subscribed to a channel.\n", + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "subscribers": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A list containing the IDs of all active users who are subscribed\nto the channel.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "subscribers": [11, 26] + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the requested channel does not exist,\nor where the user does not have permission to access the target channel:\n" + } + ] + } + } + } + } + } + } + }, + "/streams": { + "get": { + "operationId": "get-streams", + "summary": "Get all channels", + "tags": ["channels"], + "description": "Get all channels that the user [has access to](/help/channel-permissions).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": [""] + } + }, + { + "type": "include", + "parameters": { + "enum": ["include_public"] + }, + "description": "You may pass in one or more of the parameters mentioned below\nas URL query parameters, like so:\n" + } + ] + }, + "parameters": [ + { + "name": "include_public", + "in": "query", + "description": "Include all public channels.\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + { + "name": "include_web_public", + "in": "query", + "description": "Include all web-public channels.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "include_subscribed", + "in": "query", + "description": "Include all channels that the user is subscribed to.\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + { + "name": "exclude_archived", + "in": "query", + "description": "Whether to exclude archived streams from the results.\n\n**Changes**: New in Zulip 10.0 (feature level 315).\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": true + }, + { + "name": "include_all_active", + "in": "query", + "description": "Deprecated parameter to include all channels. The user must\nhave administrative privileges to use this parameter.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level\n356). Clients interacting with newer servers should use\nthe equivalent `include_all` parameter, which does not\nincorrectly hint that this parameter, and not\n`exclude_archived`, controls whether archived channels\nappear in the response.\n", + "schema": { + "type": "boolean", + "default": false + }, + "deprecated": true, + "example": true + }, + { + "name": "include_all", + "in": "query", + "description": "Include all channels that the user has metadata access to.\n\nFor organization administrators, this will be all channels\nin the organization, since organization administrators\nimplicitly have metadata access to all channels.\n\n**Changes**: New in Zulip 10.0 (feature level 356). On older\nversions, use `include_all_active`, which this replaces.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "include_default", + "in": "query", + "description": "Include all default channels for the user's realm.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "include_owner_subscribed", + "in": "query", + "description": "If the user is a bot, include all channels that the bot's owner is\nsubscribed to.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "include_can_access_content", + "in": "query", + "description": "Include all the channels that the user has content access to.\n\n**Changes**: New in Zulip 10.0 (feature level 356).\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "streams": { + "description": "A list of channel objects with details on the requested channels.\n", + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/BasicChannelBase" + }, + { + "additionalProperties": false, + "properties": { + "stream_id": {}, + "name": {}, + "is_archived": {}, + "description": {}, + "date_created": {}, + "creator_id": { + "nullable": true + }, + "invite_only": {}, + "rendered_description": {}, + "is_web_public": {}, + "stream_post_policy": {}, + "message_retention_days": { + "nullable": true + }, + "history_public_to_subscribers": {}, + "topics_policy": {}, + "first_message_id": { + "nullable": true + }, + "folder_id": { + "nullable": true + }, + "is_recently_active": {}, + "is_announcement_only": {}, + "can_add_subscribers_group": {}, + "can_remove_subscribers_group": {}, + "can_administer_channel_group": {}, + "can_delete_any_message_group": {}, + "can_delete_own_message_group": {}, + "can_move_messages_out_of_channel_group": {}, + "can_move_messages_within_channel_group": {}, + "can_send_message_group": {}, + "can_resolve_topics_group": {}, + "can_subscribe_group": {}, + "subscriber_count": {}, + "stream_weekly_traffic": { + "type": "integer", + "nullable": true, + "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, no information is provided on the average traffic.\nThis can be because the channel was recently created and there\nis insufficient data to make an estimate, or because the server\nwishes to omit this information for this client, this realm, or\nthis endpoint or type of event.\n\n**Changes**: New in Zulip 8.0 (feature level 199). Previously,\nthis statistic was available only in subscription objects.\n" + }, + "is_default": { + "type": "boolean", + "description": "Only present when [`include_default`][include_default]\nparameter is `true`.\n\nWhether the given channel is a\n[default channel](/help/set-default-channels-for-new-users).\n\n[include_default]: /api/get-streams#parameter-include_default\n" + } + }, + "required": [ + "stream_id", + "name", + "is_archived", + "description", + "date_created", + "creator_id", + "invite_only", + "rendered_description", + "is_web_public", + "stream_post_policy", + "message_retention_days", + "history_public_to_subscribers", + "first_message_id", + "folder_id", + "is_announcement_only", + "can_remove_subscribers_group", + "can_subscribe_group", + "stream_weekly_traffic", + "is_recently_active", + "subscriber_count" + ] + } + ] + } + } + }, + "example": { + "msg": "", + "result": "success", + "streams": [ + { + "can_add_subscribers_group": 10, + "can_remove_subscribers_group": 10, + "can_subscribe_group": 10, + "creator_id": null, + "date_created": 1691057093, + "description": "A private channel", + "first_message_id": 18, + "folder_id": 1, + "is_recently_active": true, + "history_public_to_subscribers": false, + "invite_only": true, + "is_announcement_only": false, + "is_archived": false, + "is_default": false, + "is_web_public": false, + "message_retention_days": null, + "name": "management", + "rendered_description": "

A private channel

", + "stream_id": 2, + "stream_post_policy": 1, + "stream_weekly_traffic": null, + "subscriber_count": 20 + }, + { + "can_add_subscribers_group": 9, + "can_remove_subscribers_group": 9, + "can_subscribe_group": 10, + "creator_id": 12, + "date_created": 1691057093, + "description": "A default public channel", + "first_message_id": 21, + "folder_id": null, + "is_recently_active": true, + "history_public_to_subscribers": true, + "invite_only": false, + "is_announcement_only": false, + "is_archived": false, + "is_default": true, + "is_web_public": false, + "message_retention_days": null, + "name": "welcome", + "rendered_description": "

A default public channel

", + "stream_id": 1, + "stream_post_policy": 1, + "stream_weekly_traffic": null, + "subscriber_count": 10 + } + ] + } + } + ] + } + } + } + } + } + } + }, + "/streams/{stream_id}": { + "get": { + "operationId": "get-stream-by-id", + "summary": "Get a channel by ID", + "tags": ["channels"], + "description": "Fetch details for the channel with the ID `stream_id`.\n\n**Changes**: New in Zulip 6.0 (feature level 132).\n", + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "stream": { + "$ref": "#/components/schemas/BasicChannel" + } + }, + "example": { + "msg": "", + "result": "success", + "stream": { + "description": "A Scandinavian country", + "first_message_id": 1, + "folder_id": 1, + "is_recently_active": true, + "history_public_to_subscribers": true, + "date_created": 1691057093, + "creator_id": null, + "invite_only": false, + "is_announcement_only": false, + "is_archived": false, + "is_web_public": false, + "message_retention_days": null, + "name": "Denmark", + "rendered_description": "

A Scandinavian country

", + "stream_id": 7, + "stream_post_policy": 1, + "can_add_subscribers_group": 2, + "can_remove_subscribers_group": 2, + "can_subscribe_group": 2, + "stream_weekly_traffic": null, + "subscriber_count": 12 + } + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the channel ID is not valid:\n" + } + ] + } + } + } + } + } + }, + "delete": { + "operationId": "archive-stream", + "summary": "Archive a channel", + "tags": ["channels"], + "description": "[Archive the channel](/help/archive-a-channel) with the ID `stream_id`.\n", + "x-requires-administrator": true, + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the supplied channel does not exist:\n" + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "update-stream", + "summary": "Update a channel", + "tags": ["channels"], + "description": "Configure the channel with the ID `stream_id`. This endpoint supports\nan organization administrator editing any property of a channel,\nincluding:\n\n- Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description)\n- Channel [permissions](/help/channel-permissions), including\n [privacy](/help/change-the-privacy-of-a-channel) and [who can\n send](/help/channel-posting-policy).\n\nNote that an organization administrator's ability to change a\n[private channel's permissions](/help/channel-permissions#private-channels)\ndepends on them being subscribed to the channel.\n\n**Changes**: Before Zulip 10.0 (feature level 362), channel privacy could not be\nedited for archived channels.\n\nRemoved `stream_post_policy` and `is_announcement_only`\nparameters in Zulip 10.0 (feature level 333), as permission to post\nin the channel is now controlled by `can_send_message_group`.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["new_name", "description", "is_private"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "description": { + "description": "The new [description](/help/change-the-channel-description) for\nthe channel, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 4.0 (feature level 64).\n", + "type": "string", + "example": "Discuss Italian history and travel destinations." + }, + "new_name": { + "description": "The new name for the channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 4.0 (feature level 64).\n", + "type": "string", + "example": "Italy" + }, + "is_private": { + "description": "Change whether the channel is a private channel.\n", + "type": "boolean", + "example": true + }, + "is_web_public": { + "description": "Change whether the channel is a web-public channel.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current use to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 98).\n", + "type": "boolean", + "example": true + }, + "history_public_to_subscribers": { + "description": "Whether the channel's message history should be available to\nnewly subscribed members, or users can only access messages\nthey actually received while subscribed to the channel.\n\nCorresponds to the shared history option for\n[private channels](/help/channel-permissions#private-channels).\n\nIt's an error for this parameter to be false for a public or\nweb-public channel and when is_private is false.\n\n**Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers`\nwas silently ignored unless the request also contained either `is_private` or\n`is_web_public`.\n", + "type": "boolean", + "example": false + }, + "is_default_stream": { + "description": "Add or remove the channel as a [default channel][default-channel]\nfor new users joining the organization.\n\n[default-channel]: /help/set-default-channels-for-new-users\n\n**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status\ncould only be changed using the [dedicated API endpoint](/api/add-default-stream).\n", + "type": "boolean", + "example": false + }, + "message_retention_days": { + "$ref": "#/components/schemas/MessageRetentionDays" + }, + "is_archived": { + "description": "A boolean indicating whether the channel is\n[archived](/help/archive-a-channel) or\nunarchived. Currently only allows unarchiving\npreviously archived channels.\n\n**Changes**: New in Zulip 11.0 (feature level 388).\n", + "type": "boolean", + "example": true + }, + "folder_id": { + "description": "ID of the new [channel folder](/help/channel-folders) to which the\nchannel should belong.\n\nA `null` value indicates the user wants to remove the channel from its\ncurrent channel folder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "type": "integer", + "nullable": true, + "example": 1 + }, + "topics_policy": { + "$ref": "#/components/schemas/TopicsPolicy" + }, + "can_add_subscribers_group": { + "allOf": [ + { + "description": "The set of users who have permission to add subscribers to this\nchannel expressed as an [update to a group-setting\nvalue][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nUsers who can administer the channel or have similar realm-level\npermissions can add subscribers to a public channel regardless\nof the value of this setting.\n\nUsers in this group need not be subscribed to a private channel to\nadd subscribers to it.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 342). Previously, there was no\nchannel-level setting for this permission.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_remove_subscribers_group": { + "allOf": [ + { + "description": "The set of users who have permission to unsubscribe others from this\nchannel expressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nOrganization administrators can unsubscribe others from a channel as though\nthey were in this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), channel administrators\ncould not unsubscribe other users if they were not an organization\nadministrator or part of `can_remove_subscribers_group`. Realm administrators\nwere not allowed to unsubscribe other users from a private channel if they\nwere not subscribed to that channel.\n\nPrior to Zulip 10.0 (feature level 320), this value was always the integer\nID of a system group.\n\nBefore Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`\nsetting was named `can_remove_subscribers_group_id`.\n\nNew in Zulip 7.0 (feature level 161).\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_administer_channel_group": { + "allOf": [ + { + "description": "The set of users who have permission to administer this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nOrganization administrators can administer every channel as though they were\nin this group without being explicitly listed here.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to add other subscribers to the channel.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349) a user needed to\n[have content access](/help/channel-permissions) to a channel in order\nto modify it. The exception to this rule was that organization\nadministrators can edit channel names and descriptions without having\nfull access to the channel.\n\nNew in Zulip 10.0 (feature level 325). Prior to this\nchange, the permission to administer channels was limited to realm\nadministrators.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_delete_any_message_group": { + "allOf": [ + { + "description": "The set of users who have permission to delete any message in the channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete any message in the channel.\n\nUsers present in the organization-level `can_delete_any_message_group` setting\ncan always delete any message in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in `can_delete_any_message_group` were able\ndelete any message in the organization.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_delete_own_message_group": { + "allOf": [ + { + "description": "The set of users who have permission to delete the messages that they have\nsent in the channel expressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete their own message in the channel.\n\nUsers with permission to delete any message in the channel\nand users present in the organization-level `can_delete_own_message_group` setting\ncan always delete their own messages in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in the organization-level `can_delete_any_message_group`\nand `can_delete_own_message_group` settings were able delete their own messages in\nthe organization.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_move_messages_out_of_channel_group": { + "allOf": [ + { + "description": "The set of users who have permission to move messages out of this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages out of the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_channels_group` setting can always move messages\nout of the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_channels_group` were able\nmove messages between channels.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_move_messages_within_channel_group": { + "allOf": [ + { + "description": "The set of users who have permission to move messages within this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages within the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_topics_group` setting can always move messages\nwithin the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_topics_group` were able\nmove messages between topics of a channel.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_send_message_group": { + "allOf": [ + { + "description": "The set of users who have permission to post in this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 333). Previously\n`stream_post_policy` field used to control the permission to\npost in the channel.\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_subscribe_group": { + "allOf": [ + { + "description": "The set of users who have permission to subscribe themselves to this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nEveryone, excluding guests, can subscribe to any public channel\nirrespective of this setting.\n\nUsers in this group can subscribe to a private channel as well.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 357).\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_resolve_topics_group": { + "allOf": [ + { + "description": "The set of users who have permission to to resolve topics in this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nUsers who have similar realm-level permissions can resolve topics\nin a channel regardless of the value of this setting.\n\n**Changes**: New in Zulip 11.0 (feature level 402).\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + } + } + }, + "encoding": { + "is_private": { + "contentType": "application/json" + }, + "is_web_public": { + "contentType": "application/json" + }, + "history_public_to_subscribers": { + "contentType": "application/json" + }, + "is_default_stream": { + "contentType": "application/json" + }, + "folder_id": { + "contentType": "application/json" + }, + "can_add_subscribers_group": { + "contentType": "application/json" + }, + "can_remove_subscribers_group": { + "contentType": "application/json" + }, + "can_administer_channel_group": { + "contentType": "application/json" + }, + "can_delete_any_message_group": { + "contentType": "application/json" + }, + "can_delete_own_message_group": { + "contentType": "application/json" + }, + "can_move_messages_out_of_channel_group": { + "contentType": "application/json" + }, + "can_move_messages_within_channel_group": { + "contentType": "application/json" + }, + "can_send_message_group": { + "contentType": "application/json" + }, + "can_subscribe_group": { + "contentType": "application/json" + }, + "can_resolve_topics_group": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the supplied channel does not exist:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid parameters", + "result": "error" + }, + "description": "An example JSON response for when invalid combination of channel permission\nparameters are passed:\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "A moderation request channel cannot be public.", + "result": "error" + }, + "description": "An example JSON response for when trying to set moderation request channel to\nbe public:\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/streams/{stream_id}/email_address": { + "get": { + "operationId": "get-stream-email-address", + "summary": "Get channel's email address", + "tags": ["channels"], + "description": "Get email address of a channel.\n\n**Changes**: New in Zulip 8.0 (feature level 226).\n", + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + }, + { + "name": "sender_id", + "in": "query", + "description": "The ID of a user or bot which should appear as the sender when messages\nare sent to the channel using the returned channel email address.\n\n`sender_id` can be:\n\n- ID of the current user.\n- ID of the Email gateway bot. (Default value)\n- ID of a bot owned by the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 335).\n\nPreviously, the sender was always Email gateway bot.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": false + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "email": { + "type": "string", + "description": "Email address of the channel.\n" + } + }, + "example": { + "result": "success", + "msg": "", + "email": "test.af64447e9e39374841063747ade8e6b0.show-sender@testserver" + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InvalidChannelError" + }, + { + "description": "An example JSON response for when the requested channel does not exist,\nor where the user does not have permission to access the target channel:\n" + } + ] + } + } + } + } + } + } + }, + "/streams/{stream_id}/delete_topic": { + "post": { + "operationId": "delete-topic", + "summary": "Delete a topic", + "tags": ["channels"], + "description": "Delete all messages in a topic.\n\nTopics are a field on messages (not an independent data structure), so\ndeleting all the messages in the topic deletes the topic from Zulip.\n\nBecause this endpoint deletes messages in batches, it is possible for\nthe request to time out after only deleting some messages in the topic.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages in the topic were deleted, then the success\nresponse will return `\"complete\": true`.\n\n**Changes**: Before Zulip 9.0 (feature level 256), the server never sent\n[`stream` op: `update`](/api/get-events#stream-update) events with an\nupdated `first_message_id` for a channel when the oldest message that\nhad been sent to it changed.\n\nBefore Zulip 8.0 (feature level 211), if the server's\nprocessing was interrupted by a timeout, but some messages in the topic\nwere deleted, then it would return `\"result\": \"partially_completed\"`,\nalong with a `code` field for an error string, in the success response\nto indicate that there was a timeout and that the client should repeat\nthe request.\n\nAs of Zulip 6.0 (feature level 154), instead of returning an error\nresponse when a request times out after successfully deleting some of\nthe messages in the topic, a success response is returned with\n`\"result\": \"partially_completed\"` to indicate that some messages were\ndeleted.\n\nBefore Zulip 6.0 (feature level 147), this request did a single atomic\noperation, which could time out for very large topics. As of this\nfeature level, messages are deleted in batches, starting with the newest\nmessages, so that progress is made even if the request times out and\nreturns an error.\n", + "x-requires-administrator": true, + "parameters": [ + { + "$ref": "#/components/parameters/ChannelIdInPath" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "topic_name": { + "description": "The name of the topic to delete.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", + "type": "string", + "example": "new coffee machine" + } + }, + "required": ["topic_name"] + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "required": ["complete"], + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "complete": { + "type": "boolean", + "description": "Whether all unread messages were marked as read.\n\nWill be `false` if the request successfully marked\nsome, but not all, messages as read.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "complete": true + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Must be an organization administrator", + "code": "UNAUTHORIZED_PRINCIPAL" + }, + "description": "Error when the user does not have permission\nto delete topics in this organization:\n" + } + ] + } + } + } + } + } + } + }, + "/typing": { + "post": { + "operationId": "set-typing-status", + "summary": "Set \"typing\" status", + "tags": ["users"], + "description": "Notify other users whether the current user is\n[typing a message][help-typing].\n\nClients implementing Zulip's typing notifications\nprotocol should work as follows:\n\n- Send a request to this endpoint with `\"op\": \"start\"` when a user\n starts composing a message.\n- While the user continues to actively type or otherwise interact with\n the compose UI (e.g. interacting with the compose box emoji picker),\n send regular `\"op\": \"start\"` requests to this endpoint, using\n `server_typing_started_wait_period_milliseconds` in the\n [`POST /register`][api-register] response as the time interval\n between each request.\n- Send a request to this endpoint with `\"op\": \"stop\"` when a user\n has stopped using the compose UI for the time period indicated by\n `server_typing_stopped_wait_period_milliseconds` in the\n [`POST /register`][api-register] response or when a user\n cancels the compose action (if it had previously sent a \"start\"\n notification for that compose action).\n- Start displaying a visual typing indicator for a given conversation\n when a [`typing op:start`][start-typing] event is received\n from the server.\n- Continue displaying a visual typing indicator for the conversation\n until a [`typing op:stop`][stop-typing] event is received\n from the server or the time period indicated by\n `server_typing_started_expiry_period_milliseconds` in the\n [`POST /register`][api-register] response has passed without\n a new `typing \"op\": \"start\"` event for the conversation.\n\nThis protocol is designed to allow the server-side typing notifications\nimplementation to be stateless while being resilient as network failures\nwill not result in a user being incorrectly displayed as perpetually\ntyping.\n\nSee the subsystems documentation on [typing indicators][typing-protocol-docs]\nfor additional design details on Zulip's typing notifications protocol.\n\n**Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215)\nfor channel typing notifications, as no client actually implemented\nthe previous API for those.\n\nSupport for displaying channel typing notifications was new\nin Zulip 4.0 (feature level 58). Clients should indicate they support\nprocessing channel typing notifications via the `stream_typing_notifications`\nvalue in the `client_capabilities` parameter of the\n[`POST /register`][client-capabilities] endpoint.\n\n[help-typing]: /help/typing-notifications\n[api-register]: /api/register-queue\n[start-typing]: /api/get-events#typing-start\n[stop-typing]: /api/get-events#typing-stop\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n[typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["topic"] + } + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "Type of the message being composed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate a channel message is\nbeing composed.\n\nIn Zulip 8.0 (feature level 215), stopped supporting\n`\"private\"` as a valid value for this parameter.\n\nIn Zulip 7.0 (feature level 174), `\"direct\"` was added\nas the preferred way to indicate a direct message is being composed,\nbecoming the default value for this parameter and deprecating the\noriginal `\"private\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n", + "type": "string", + "enum": ["direct", "stream", "channel"], + "default": "direct", + "example": "direct" + }, + "op": { + "description": "Whether the user has started (`\"start\"`) or stopped (`\"stop\"`) typing.\n", + "type": "string", + "enum": ["start", "stop"], + "example": "start" + }, + "to": { + "description": "User IDs of the recipients of the message being typed. Required for the\n`\"direct\"` type. Ignored in the case of `\"stream\"` or `\"channel\"` type.\n\nClients should send a JSON-encoded list of user IDs, even if there is only\none recipient.\n\n**Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter\nfor the `\"stream\"` type. Previously, in the case of the `\"stream\"` type, it\naccepted a single-element list containing the ID of the channel. A new parameter,\n`stream_id`, is now used for this. Note that the `\"channel\"` type did not\nexist at this feature level.\n\nSupport for typing notifications for channel' messages\nis new in Zulip 4.0 (feature level 58). Previously, typing\nnotifications were only for direct messages.\n\nBefore Zulip 2.0.0, this parameter accepted only a JSON-encoded\nlist of email addresses. Support for the email address-based format was\nremoved in Zulip 3.0 (feature level 11).\n", + "type": "array", + "items": { + "type": "integer" + }, + "minLength": 1, + "example": [9, 10] + }, + "stream_id": { + "description": "ID of the channel in which the message is being typed. Required for the `\"stream\"`\nor `\"channel\"` type. Ignored in the case of `\"direct\"` type.\n\n**Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element\nlist containing the ID of the channel was passed in `to` parameter.\n", + "type": "integer", + "example": 7 + }, + "topic": { + "description": "Topic to which message is being typed. Required for the `\"stream\"` or `\"channel\"`\ntype. Ignored in the case of `\"direct\"` type.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 372),\n`\"(no topic)\"` was not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n", + "type": "string", + "example": "typing notifications" + } + }, + "required": ["op"] + }, + "encoding": { + "to": { + "contentType": "application/json" + }, + "stream_id": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Missing channel ID", + "result": "error" + }, + "description": "An example JSON error response when the user composes a channel message\nand `stream_id` is not specified:\n" + } + ] + } + } + } + } + } + } + }, + "/messages/{message_id}/typing": { + "post": { + "operationId": "set-typing-status-for-message-edit", + "summary": "Set \"typing\" status for message editing", + "tags": ["users"], + "description": "Notify other users whether the current user is editing a message.\n\nTyping notifications for editing messages follow the same protocol as\n[set-typing-status](/api/set-typing-status), see that endpoint for\ndetails.\n\n**Changes**: Before Zulip 10.0 (feature level 361), the endpoint was\nnamed `/message_edit_typing` with `message_id` a required parameter in\nthe request body. Clients are recommended to start using sending these\ntyping notifications starting from this feature level.\n\nNew in Zulip 10.0 (feature level 351). Previously, typing notifications were\nnot available when editing messages.\n", + "parameters": [ + { + "name": "message_id", + "in": "path", + "description": "The target message's ID.\n", + "schema": { + "type": "integer" + }, + "example": 47, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "op": { + "description": "Whether the user has started (`\"start\"`) or stopped (`\"stop\"`) editing.\n", + "type": "string", + "enum": ["start", "stop"], + "example": "start" + } + }, + "required": ["op"] + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + } + }, + "/channels/create": { + "post": { + "tags": ["channels"], + "operationId": "create-channel", + "summary": "Create a channel", + "description": "Create a new [channel](/help/create-channels), and optionally subscribe\nusers to the newly created channel.\n\nThe initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\n**Changes**: New in Zulip 11.0 (feature level 417). Previously, this was\nonly possible via the [`POST /api/subscribe`](/api/subscribe) endpoint,\nwhich handles both channel subscription and creation.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "include", + "parameters": { + "enum": ["name", "subscribers"] + } + } + ] + }, + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the new channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n", + "example": "music" + }, + "description": { + "type": "string", + "description": "The [description](/help/change-the-channel-description)\nto use for the new channel being created, in text/markdown format.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n", + "example": "Channel for discussing all things music!" + }, + "subscribers": { + "description": "A list of user IDs of the users to be subscribed to the new channel.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [16, 12] + }, + "announce": { + "description": "This determines whether [notification bot](/help/configure-automated-notices)\nwill send an announcement about the new channel's creation.\n", + "type": "boolean", + "default": false, + "example": true + }, + "invite_only": { + "description": "This parameter and the ones that follow are used to request an initial\nconfiguration of the new channel.\n\nThis parameter determines whether the newly created channel will be\na [private channel](/help/channel-permissions#private-channels).\n", + "type": "boolean", + "default": false, + "example": true + }, + "is_web_public": { + "description": "This parameter determines whether the newly created channel will be\na web-public channel.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current user to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n", + "type": "boolean", + "default": false, + "example": true + }, + "is_default_stream": { + "description": "This parameter determines whether the newly created channel will be\nadded as a [default channel][default-channels] for new users joining\nthe organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", + "type": "boolean", + "default": false, + "example": true + }, + "folder_id": { + "description": "This parameter adds the newly created channel to the specified\n[channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "type": "integer", + "example": 1 + }, + "topics_policy": { + "$ref": "#/components/schemas/TopicsPolicy" + }, + "history_public_to_subscribers": { + "$ref": "#/components/schemas/HistoryPublicToSubscribers" + }, + "message_retention_days": { + "$ref": "#/components/schemas/MessageRetentionDays" + }, + "can_add_subscribers_group": { + "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" + }, + "can_delete_any_message_group": { + "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" + }, + "can_delete_own_message_group": { + "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" + }, + "can_remove_subscribers_group": { + "$ref": "#/components/schemas/CanRemoveSubscribersGroup" + }, + "can_administer_channel_group": { + "$ref": "#/components/schemas/CanAdministerChannelGroup" + }, + "can_move_messages_out_of_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" + }, + "can_move_messages_within_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" + }, + "can_send_message_group": { + "$ref": "#/components/schemas/CanSendMessageGroup" + }, + "can_subscribe_group": { + "$ref": "#/components/schemas/CanSubscribeGroup" + }, + "can_resolve_topics_group": { + "$ref": "#/components/schemas/CanResolveTopicsGroup" + } + }, + "required": ["name", "subscribers"] + }, + "encoding": { + "announce": { + "contentType": "application/json" + }, + "can_add_subscribers_group": { + "contentType": "application/json" + }, + "can_administer_channel_group": { + "contentType": "application/json" + }, + "can_move_messages_out_of_channel_group": { + "contentType": "application/json" + }, + "can_move_messages_within_channel_group": { + "contentType": "application/json" + }, + "can_remove_subscribers_group": { + "contentType": "application/json" + }, + "can_resolve_topics_group": { + "contentType": "application/json" + }, + "can_send_message_group": { + "contentType": "application/json" + }, + "can_subscribe_group": { + "contentType": "application/json" + }, + "subscribers": { + "contentType": "application/json" + }, + "invite_only": { + "contentType": "application/json" + }, + "is_web_public": { + "contentType": "application/json" + }, + "is_default_stream": { + "contentType": "application/json" + }, + "history_public_to_subscribers": { + "contentType": "application/json" + }, + "folder_id": { + "contentType": "application/json" + }, + "topics_policy": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "id": { + "type": "integer", + "description": "The ID of the newly created channel." + } + } + } + ], + "example": { + "result": "success", + "msg": "", + "id": 50 + } + } + } + } + }, + "409": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Channel 'discussions' already exists", + "code": "CHANNEL_ALREADY_EXISTS" + }, + "description": "An example JSON error response for when a channel with the submitted\nname already exists.\n" + } + ] + } + } + } + } + } + } + }, + "/user_groups/create": { + "post": { + "operationId": "create-user-group", + "summary": "Create a user group", + "tags": ["users"], + "description": "Create a new [user group](/help/user-groups).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the user group.\n", + "type": "string", + "example": "marketing" + }, + "description": { + "description": "The description of the user group.\n", + "type": "string", + "example": "The marketing team." + }, + "members": { + "description": "An array containing the user IDs of the initial members for the\nnew user group.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [1, 2, 3, 4] + }, + "subgroups": { + "description": "An array containing the IDs of the initial subgroups for the new\nuser group.\n\nUser can add subgroups to the new group irrespective of other\npermissions for the new group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [11] + }, + "can_add_members_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 11 + }, + "can_join_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 11 + }, + "can_leave_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 15 + }, + "can_manage_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:everyone\"`\n[system groups][system-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[manage-user-groups]: /help/manage-user-groups\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 11 + }, + "can_mention_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:owners\"`\n[system groups][system-groups].\n\nBefore Zulip 9.0 (feature level 258), this parameter could only be the\ninteger form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this parameter was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 11 + }, + "can_remove_members_group": { + "allOf": [ + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ], + "example": 11 + } + }, + "required": ["name", "description", "members"] + }, + "encoding": { + "members": { + "contentType": "application/json" + }, + "subgroups": { + "contentType": "application/json" + }, + "can_add_members_group": { + "contentType": "application/json" + }, + "can_join_group": { + "contentType": "application/json" + }, + "can_leave_group": { + "contentType": "application/json" + }, + "can_manage_group": { + "contentType": "application/json" + }, + "can_mention_group": { + "contentType": "application/json" + }, + "can_remove_members_group": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "A success response containing the unique ID of the user group.\nThis field provides a straightforward way to reference the\nnewly created user group.\n\n**Changes**: New in Zulip 10.0 (feature level 317).\n", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": ["group_id"], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "group_id": { + "type": "integer", + "description": "The unique ID of the created user group.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "group_id": 123 + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "code": "BAD_REQUEST", + "msg": "Invalid user ID: 500" + }, + "description": "An example JSON error response for when the one of the users does not exist:\n" + } + ] + } + } + } + } + } + } + }, + "/user_groups/{user_group_id}/members": { + "post": { + "operationId": "update-user-group-members", + "summary": "Update user group members", + "tags": ["users"], + "description": "Update the members of a [user group](/help/user-groups). The\nuser IDs must correspond to non-deactivated users.\n\n**Changes**: Prior to Zulip 11.0 (feature level 391), members\ncould not be added or removed from a deactivated group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of\ndeactivated users were visible to the API and could be edited via this endpoint.\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["delete"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "delete": { + "description": "The list of user IDs to be removed from the user group.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [10] + }, + "add": { + "description": "The list of user IDs to be added to the user group.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [12, 13] + }, + "delete_subgroups": { + "description": "The list of user group IDs to be removed from the user group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [9] + }, + "add_subgroups": { + "description": "The list of user group IDs to be added to the user group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [9] + } + } + }, + "encoding": { + "delete": { + "contentType": "application/json" + }, + "add": { + "contentType": "application/json" + }, + "delete_subgroups": { + "contentType": "application/json" + }, + "add_subgroups": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + }, + "get": { + "operationId": "get-user-group-members", + "summary": "Get user group members", + "tags": ["users"], + "description": "Get the members of a [user group](/help/user-groups).\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + }, + { + "$ref": "#/components/parameters/DirectMemberOnly" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "members": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A list containing the user IDs of members of the user group.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "members": [10, 12] + } + } + ] + } + } + } + } + } + } + }, + "/user_groups/{user_group_id}": { + "patch": { + "operationId": "update-user-group", + "summary": "Update a user group", + "tags": ["users"], + "description": "Update the name, description or any of the permission settings\nof a [user group](/help/user-groups).\n\nThis endpoint is also used to reactivate a user group.\n\nNote that while permissions settings of deactivated groups can\nbe edited by this API endpoint, and those permissions settings\ndo affect the ability to modify the deactivated group and its\nmembership, the deactivated group itself cannot be mentioned\nor used in the value of any permission without first being reactivated.\n\n**Changes**: Starting with Zulip 11.0 (feature level 386), this\nendpoint can be used to reactivate a user group.\n\nPrior to Zulip 10.0 (feature level 340), only the name field\nof deactivated groups could be modified.\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The new name of the group.\n\n**Changes**: Before Zulip 7.0 (feature level 165), this was\na required field.\n", + "type": "string", + "example": "marketing team" + }, + "description": { + "description": "The new description of the group.\n\n**Changes**: Before Zulip 7.0 (feature level 165), this was\na required field.\n", + "type": "string", + "example": "The marketing team." + }, + "can_add_members_group": { + "allOf": [ + { + "description": "The set of users who have permission to add members to this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 11 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_join_group": { + "allOf": [ + { + "description": "The set of users who have permission to join this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 11 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_leave_group": { + "allOf": [ + { + "description": "The set of users who have permission to leave this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 15 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_manage_group": { + "allOf": [ + { + "description": "The set of users who have permission to [manage this user group][manage-user-groups]\nexpressed as an [update to a group-setting value][update-group-setting].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:everyone\"`\n[system groups][system-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[manage-user-groups]: /help/manage-user-groups\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 11 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_mention_group": { + "allOf": [ + { + "description": "The set of users who have permission to [mention this group][mentions],\nexpressed as an [update to a group-setting value][update-group-setting].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:owners\"`\n[system groups][system-groups].\n\n**Changes**: In Zulip 9.0 (feature level 260), this parameter was\nupdated to only accept an object with the `old` and `new` fields\ndescribed below. Prior to this feature level, this parameter could be\neither of the two forms of a [group-setting value][setting-values].\n\nBefore Zulip 9.0 (feature level 258), this parameter could only be the\ninteger form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this parameter was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\n[mentions]: /help/mention-a-user-or-group\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[setting-values]: /api/group-setting-values\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 11 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "can_remove_members_group": { + "allOf": [ + { + "description": "The set of users who have permission to remove members from this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", + "example": { + "new": { + "direct_members": [10], + "direct_subgroups": [11] + }, + "old": 11 + } + }, + { + "$ref": "#/components/schemas/GroupSettingValueUpdate" + } + ] + }, + "deactivated": { + "description": "A deactivated user group can be reactivated by passing this\nparameter as `false`.\n\nPassing `true` does nothing as user group is deactivated\nusing [`POST /user_groups/{user_group_id}/deactivate`](deactivate-user-group)\nendpoint.\n\n**Changes**: New in Zulip 11.0 (feature level 386).\n", + "type": "boolean", + "example": false + } + } + }, + "encoding": { + "can_add_members_group": { + "contentType": "application/json" + }, + "can_join_group": { + "contentType": "application/json" + }, + "can_leave_group": { + "contentType": "application/json" + }, + "can_manage_group": { + "contentType": "application/json" + }, + "can_mention_group": { + "contentType": "application/json" + }, + "can_remove_members_group": { + "contentType": "application/json" + }, + "deactivated": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid user group", + "result": "error" + }, + "description": "An example JSON response when the user group ID is invalid:\n" + } + ] + } + } + } + } + } + } + }, + "/user_groups": { + "get": { + "operationId": "get-user-groups", + "summary": "Get user groups", + "tags": ["users"], + "description": "Fetches all of the user groups in the organization.\n\n!!! warn \"\"\n\n **Note**: This endpoint is only available to [members and\n administrators](/help/user-roles); bots and guests\n cannot use this endpoint.\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "include_deactivated_groups": { + "description": "Whether to include deactivated user groups in the response.\n\n**Changes**: In Zulip 10.0 (feature level 294), renamed\n`allow_deactivated` to `include_deactivated_groups`.\n\nNew in Zulip 10.0 (feature level 290). Previously, deactivated\nuser groups did not exist and thus would never be included in\nthe response.\n", + "type": "boolean", + "example": true, + "default": false + } + } + }, + "encoding": { + "allow_deactivated": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "user_groups": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "type": "string", + "description": "The human-readable description of the user group.\n" + }, + "id": { + "type": "integer", + "description": "The user group's integer ID.\n" + }, + "date_created": { + "type": "integer", + "nullable": true, + "description": "The UNIX timestamp for when the user group was created, in UTC seconds.\n\nA `null` value means the user group has no recorded date, which is often\nbecause the group predates the metadata being tracked starting in Zulip 8.0,\nor because it was created via a data import tool\nor [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "creator_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who created this user group.\n\nA `null` value means the user group has no recorded creator, which is often\nbecause the group predates the metadata being tracked starting in Zulip 8.0,\nor because it was created via a data import tool\nor [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "members": { + "type": "array", + "description": "The integer user IDs of the user group's members, which\nare guaranteed to be non-deactivated users in the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this\nlist also included deactivated users who were members of\nthe user group before being deactivated.\n", + "items": { + "type": "integer" + } + }, + "direct_subgroup_ids": { + "type": "array", + "description": "The integer user group IDs of the direct subgroups.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nIntroduced in feature level 127 as `subgroups`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n", + "items": { + "type": "integer" + } + }, + "name": { + "type": "string", + "description": "User group name.\n" + }, + "is_system_group": { + "type": "boolean", + "description": "Whether the user group is a system group which cannot be\nmodified by users.\n\n**Changes**: New in Zulip 5.0 (feature level 93).\n" + }, + "can_add_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_join_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_leave_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_manage_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" + } + ] + }, + "can_mention_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" + } + ] + }, + "can_remove_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "deactivated": { + "type": "boolean", + "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" + } + } + }, + "description": "A list of `user_group` objects.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "user_groups": [ + { + "description": "Owners of this organization", + "id": 1, + "creator_id": null, + "date_created": null, + "name": "role:owners", + "members": [1], + "direct_subgroup_ids": [], + "is_system_group": true, + "can_add_members_group": 16, + "can_join_group": 16, + "can_leave_group": 15, + "can_manage_group": 16, + "can_mention_group": 11, + "can_remove_members_group": 16 + }, + { + "description": "Administrators of this organization, including owners", + "id": 2, + "creator_id": null, + "date_created": null, + "name": "role:administrators", + "members": [2], + "direct_subgroup_ids": [1], + "is_system_group": true, + "can_add_members_group": 17, + "can_join_group": 17, + "can_leave_group": 15, + "can_manage_group": 17, + "can_mention_group": 12, + "can_remove_members_group": 16 + }, + { + "description": "Characters of Hamlet", + "id": 3, + "creator_id": null, + "date_created": 1717484476, + "name": "hamletcharacters", + "members": [3, 4], + "direct_subgroup_ids": [], + "is_system_group": false, + "can_add_members_group": 20, + "can_join_group": 20, + "can_leave_group": 15, + "can_manage_group": 20, + "can_mention_group": 13, + "can_remove_members_group": 16 + } + ] + } + } + ] + } + } + } + } + } + } + }, + "/user_groups/{user_group_id}/subgroups": { + "post": { + "operationId": "update-user-group-subgroups", + "summary": "Update subgroups of a user group", + "tags": ["users"], + "description": "Update the subgroups of a [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 11.0 (feature level 391), subgroups\ncould not be added or removed from a deactivated group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", + "x-curl-examples-parameters": { + "oneOf": [ + { + "type": "exclude", + "parameters": { + "enum": ["delete"] + } + } + ] + }, + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "delete": { + "description": "The list of user group IDs to be removed from the user group.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [10] + }, + "add": { + "description": "The list of user group IDs to be added to the user group.\n", + "type": "array", + "items": { + "type": "integer" + }, + "example": [10] + } + } + }, + "encoding": { + "delete": { + "contentType": "application/json" + }, + "add": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + } + } + }, + "get": { + "operationId": "get-user-group-subgroups", + "summary": "Get subgroups of a user group", + "tags": ["users"], + "description": "Get the subgroups of a [user group](/help/user-groups).\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + }, + { + "name": "direct_subgroup_only", + "in": "query", + "description": "Whether to consider only direct subgroups of the user group\nor subgroups of subgroups also.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true, + "required": false + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "subgroups": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A list containing the IDs of subgroups of the user group.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "subgroups": [2, 3] + } + } + ] + } + } + } + } + } + } + }, + "/user_groups/{user_group_id}/members/{user_id}": { + "get": { + "operationId": "get-is-user-group-member", + "summary": "Get user group membership status", + "tags": ["users"], + "description": "Check whether a user is member of user group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303),\nthis would return true when passed a deactivated user\nwho was a member of the user group before being deactivated.\n\nNew in Zulip 6.0 (feature level 127).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + }, + { + "$ref": "#/components/parameters/UserId" + }, + { + "$ref": "#/components/parameters/DirectMemberOnly" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "is_user_group_member": { + "type": "boolean", + "description": "Whether the user is member of user group.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "is_user_group_member": false + } + } + ] + } + } + } + } + } + } + }, + "/user_groups/{user_group_id}/deactivate": { + "post": { + "operationId": "deactivate-user-group", + "summary": "Deactivate a user group", + "tags": ["users"], + "description": "Deactivate a user group. Deactivated user groups cannot be\nused for mentions, permissions, or any other purpose, but can\nbe reactivated or renamed.\n\nDeactivating user groups is preferable to deleting them from\nthe database, since the deactivation model allows audit logs\nof changes to sensitive group-valued permissions to be\nmaintained.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n", + "parameters": [ + { + "$ref": "#/components/parameters/UserGroupId" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid user group", + "result": "error" + }, + "description": "An example JSON response when the user group ID is invalid.\n" + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "CANNOT_DEACTIVATE_GROUP_IN_USE", + "msg": "Cannot deactivate user group in use.", + "objections": [ + { + "type": "realm", + "settings": ["can_create_public_channel_group"] + } + ], + "result": "error" + }, + "description": "An example JSON response when the user group being deactivated\nis used for a setting or as a subgroup.\n\n**Changes**: New in Zulip 10.0 (feature level 298). Previously,\nthis error returned the `\"BAD_REQUEST\"` code.\n" + } + ] + } + ] + } + } + } + } + } + } + }, + "/channel_folders/create": { + "post": { + "operationId": "create-channel-folder", + "summary": "Create a channel folder", + "tags": ["channels"], + "x-requires-administrator": true, + "description": "Create a new [channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the channel folder.\n\nClients should use the `max_channel_folder_name_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel folder name length.\n\nValue cannot be an empty string.\n", + "type": "string", + "example": "marketing" + }, + "description": { + "description": "The description of the channel folder.\n\nClients should use the `max_channel_folder_description_length`\nreturned by the [`POST /register`](/api/register-queue) endpoint\nto determine the maximum channel folder description length.\n\nNote that this parameter must be passed as part of the request,\nbut can be an empty string if no description for the new channel\nfolder is desired.\n", + "type": "string", + "example": "Channels for marketing." + } + }, + "required": ["name"] + } + } + } + }, + "responses": { + "200": { + "description": "A success response containing the unique ID of the channel folder.\nThis field provides a straightforward way to reference the\nnewly created channel folder.\n", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": ["channel_folder_id"], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "channel_folder_id": { + "type": "integer", + "description": "The unique ID of the created channel folder.\n" + } + }, + "example": { + "msg": "", + "result": "success", + "channel_folder_id": 12 + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "result": "error", + "msg": "Must be an organization administrator", + "code": "UNAUTHORIZED_PRINCIPAL" + }, + "description": "Error when the user does not have permission\nto create a channel folder:\n" + } + ] + } + } + } + } + } + } + }, + "/channel_folders": { + "get": { + "operationId": "get-channel-folders", + "summary": "Get channel folders", + "tags": ["channels"], + "description": "Fetches all of the [channel folders](/help/channel-folders) in the\norganization, sorted by the `order` field.\n\n**Changes**: Before Zulip 11.0 (feature level 414), the list of channel\nfolders was sorted by ID as the `order` field didn't exist.\n\nNew in Zulip 11.0 (feature level 389).\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "include_archived": { + "description": "Whether to include archived channel folders in the response.\n", + "type": "boolean", + "example": true, + "default": false + } + } + }, + "encoding": { + "include_archived": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "channel_folders": { + "type": "array", + "description": "A list of channel folder objects.\n", + "items": { + "$ref": "#/components/schemas/ChannelFolder" + } + } + }, + "example": { + "msg": "", + "result": "success", + "channel_folders": [ + { + "description": "Channels for frontend discussions", + "rendered_description": "

Channels for frontend discussions

", + "id": 1, + "creator_id": 1, + "date_created": 1691057093, + "name": "Frontend", + "is_archived": false + }, + { + "description": "Channels for **backend** discussions", + "rendered_description": "

Channels for backend discussions

", + "id": 2, + "creator_id": 1, + "date_created": 1791057093, + "name": "Backend", + "is_archived": false + } + ] + } + } + ] + } + } + } + } + } + }, + "patch": { + "operationId": "patch-channel-folders", + "summary": "Reorder channel folders", + "tags": ["channels"], + "x-requires-administrator": true, + "description": "Reorder the [channel folders](/help/channel-folders) in the user's\norganization.\n\nChannel folders are displayed in Zulip UI in order; this endpoint allows\nadministrative settings UI to change the ordering of channel folders.\n\nThis endpoint is used to implement the dragging feature described in the\n[manage channel folders documentation](/help/manage-channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 414).\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "order": { + "type": "array", + "description": "A list of channel folder IDs representing the new order.\n\nThis list must include the IDs of [all the organization's channel\nfolders](/api/get-channel-folders), including archived folders.\n", + "items": { + "type": "integer" + }, + "example": [2, 1] + } + }, + "required": ["order"] + }, + "encoding": { + "order": { + "contentType": "application/json" + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid order mapping", + "result": "error" + }, + "description": "An example JSON response when the order mapping is invalid:\n" + } + ] + } + } + } + } + } + } + }, + "/channel_folders/{channel_folder_id}": { + "patch": { + "operationId": "update-channel-folder", + "summary": "Update a channel folder", + "tags": ["channels"], + "x-requires-administrator": true, + "description": "Update the name or description of a [channel folder](/help/channel-folders)\nwith the specified ID.\n\nThis endpoint is also used to archive or unarchive the specified channel\nfolder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", + "parameters": [ + { + "$ref": "#/components/parameters/ChannelFolderId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The new name of the channel folder.\n\nClients should use the `max_channel_folder_name_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel folder name length.\n\nValue cannot be an empty string.\n", + "type": "string", + "example": "backend" + }, + "description": { + "description": "The new description of the channel folder.\n\nClients should use the `max_channel_folder_description_length`\nreturned by the [`POST /register`](/api/register-queue) endpoint\nto determine the maximum channel folder description length.\n", + "type": "string", + "example": "Backend channels." + }, + "is_archived": { + "description": "Whether to archive or unarchive the channel folder.\n", + "type": "boolean", + "example": true + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SimpleSuccess" + }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "Invalid channel folder ID", + "result": "error" + }, + "description": "An example JSON response when the channel folder ID is invalid:\n" + } + ] + } + } + } + } + } + } + }, + "/real-time": { + "post": { + "tags": ["real_time_events"], + "description": "(Ignored)\n", + "requestBody": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "event_types": { + "$ref": "#/components/schemas/Event_types" + }, + "narrow": { + "$ref": "#/components/schemas/Narrow" + }, + "all_public_streams": { + "$ref": "#/components/schemas/AllPublicChannels" + } + } + }, + "encoding": { + "event_types": { + "contentType": "application/json" + }, + "narrow": { + "contentType": "application/json" + }, + "all_public_streams": { + "contentType": "application/json" + } + } + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "responses": { + "200": { + "description": "Success" + } + } + } + }, + "/rest-error-handling": { + "post": { + "operationId": "rest-error-handling", + "summary": "Error handling", + "tags": ["real_time_events"], + "description": "Common error to many endpoints\n", + "responses": { + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/InvalidApiKeyError" + }, + { + "$ref": "#/components/schemas/MissingArgumentError" + }, + { + "$ref": "#/components/schemas/IncompatibleParametersError" + }, + { + "$ref": "#/components/schemas/UserNotAuthorizedError" + } + ] + } + } + } + }, + "401": { + "description": "Unauthorized.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/UserDeactivatedError" + }, + { + "$ref": "#/components/schemas/RealmDeactivatedError" + } + ] + } + } + } + }, + "429": { + "description": "Rate limit exceeded.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RateLimitedError" + } + ] + } + } + } + } + } + } + }, + "/zulip-outgoing-webhook": { + "post": { + "operationId": "zulip-outgoing-webhooks", + "summary": "Outgoing webhooks", + "tags": ["webhooks"], + "description": "Outgoing webhooks allow you to build or set up Zulip integrations which are\nnotified when certain types of messages are sent in Zulip.\n", + "responses": { + "200": { + "description": "Success\n", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "description": "This is an example of the JSON payload that the Zulip server will `POST`\nto your server:\n", + "properties": { + "bot_email": { + "type": "string", + "description": "Email of the bot user.\n" + }, + "bot_full_name": { + "type": "string", + "description": "The full name of the bot user.\n" + }, + "data": { + "type": "string", + "description": "The message content, in raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format (not rendered to HTML).\n" + }, + "trigger": { + "type": "string", + "description": "What aspect of the message triggered the outgoing webhook notification.\nPossible values include `direct_message` and `mention`.\n\n**Changes**: In Zulip 8.0 (feature level 201), renamed the trigger\n`private_message` to `direct_message`.\n" + }, + "token": { + "type": "string", + "description": "A string of alphanumeric characters that can be used to authenticate the\nwebhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot\nin the `zuliprc` file downloaded when creating the bot.\n" + }, + "message": { + "description": "A dictionary containing details on the message that triggered the\noutgoing webhook, in the format used by [`GET /messages`](/api/get-messages).\n", + "allOf": [ + { + "$ref": "#/components/schemas/MessagesBase" + }, + { + "additionalProperties": false, + "properties": { + "avatar_url": { + "nullable": true + }, + "client": {}, + "content": {}, + "content_type": {}, + "display_recipient": {}, + "edit_history": {}, + "id": {}, + "is_me_message": {}, + "last_edit_timestamp": {}, + "last_moved_timestamp": {}, + "reactions": {}, + "recipient_id": {}, + "sender_email": {}, + "sender_full_name": {}, + "sender_id": {}, + "sender_realm_str": {}, + "stream_id": {}, + "subject": {}, + "submessages": {}, + "timestamp": {}, + "topic_links": {}, + "type": {}, + "rendered_content": { + "type": "string", + "description": "The content/body of the message rendered in HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + } + } + } + ] + } + }, + "example": { + "data": "@**Outgoing webhook test** Zulip is the world’s most productive group chat!", + "trigger": "mention", + "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0", + "message": { + "subject": "Verona2", + "sender_email": "iago@zulip.com", + "timestamp": 1527876931, + "client": "website", + "submessages": [], + "recipient_id": 20, + "topic_links": [], + "sender_full_name": "Iago", + "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1", + "rendered_content": "

@Outgoing webhook test Zulip is the world’s most productive group chat!

", + "sender_id": 5, + "stream_id": 5, + "content": "@**Outgoing webhook test** Zulip is the world’s most productive group chat!", + "display_recipient": "Verona", + "type": "stream", + "id": 112, + "is_me_message": false, + "reactions": [], + "sender_realm_str": "zulip" + }, + "bot_email": "outgoing-bot@localhost", + "bot_full_name": "Outgoing webhook test" + } + } + } + } + } + } + } + }, + "/calls/bigbluebutton/create": { + "get": { + "tags": ["channels"], + "operationId": "create-big-blue-button-video-call", + "summary": "Create BigBlueButton video call", + "description": "Create a video call URL for a BigBlueButton video call.\nRequires [BigBlueButton 2.4+](/integrations/doc/big-blue-button)\nto be configured on the Zulip server.\n\nThe acting user will be given the moderator role on the call.\n\n**Changes**: Prior to Zulip 10.0 (feature level 337), every\nuser was given the moderator role on BigBlueButton calls, via\nencoding a moderator password in the generated URLs.\n", + "parameters": [ + { + "in": "query", + "name": "meeting_name", + "schema": { + "type": "string" + }, + "required": true, + "description": "Meeting name for the BigBlueButton video call.\n", + "example": "test_channel meeting" + }, + { + "in": "query", + "name": "voice_only", + "schema": { + "type": "boolean" + }, + "required": false, + "description": "Configures whether the call is voice-only; if true,\ndisables cameras for all users. Only the call\ncreator/moderator can edit this configuration.\n\n**Changes**: New in Zulip 10.0 (feature level 337).\n", + "example": true + } + ], + "responses": { + "200": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "url": { + "description": "The URL for the BigBlueButton video call.\n", + "type": "string", + "example": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22" + } + }, + "example": { + "msg": "", + "result": "success", + "url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" + } + } + ] + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "BasicAuth": { + "type": "http", + "scheme": "basic", + "description": "Basic authentication, with the user's email as the username, and the API\nkey as the password. The API key can be fetched using the\n`/fetch_api_key` or `/dev_fetch_api_key` endpoints.\n" + } + }, + "schemas": { + "IgnoredParametersUnsupported": { + "type": "array", + "items": { + "type": "string" + }, + "description": "An array of any parameters sent in the request that are not\nsupported by the endpoint.\n\nSee [error handling](/api/rest-error-handling#ignored-parameters) documentation\nfor details on this and its change history.\n" + }, + "EventIdSchema": { + "type": "integer", + "description": "The ID of the event. Events appear in increasing order but may not be consecutive.\n" + }, + "EventTypeSchema": { + "type": "string", + "description": "The event's type, relevant both for client-side dispatch and server-side\nfiltering by event type in [POST /register](/api/register-queue).\n" + }, + "Anchor": { + "type": "string" + }, + "Attachment": { + "type": "object", + "description": "Dictionary containing details of a file uploaded by a user.\n", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "The unique ID for the attachment.\n" + }, + "name": { + "type": "string", + "description": "Name of the uploaded file.\n" + }, + "path_id": { + "type": "string", + "description": "A representation of the path of the file within the\nrepository of user-uploaded files. If the `path_id` of a\nfile is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:\n`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.\n" + }, + "size": { + "type": "integer", + "description": "Size of the file in bytes.\n" + }, + "create_time": { + "type": "integer", + "description": "Time when the attachment was uploaded as a UNIX timestamp\nmultiplied by 1000 (matching the format of getTime() in JavaScript).\n\n**Changes**: Changed in Zulip 3.0 (feature level 22). This field was\npreviously a floating point number.\n" + }, + "messages": { + "type": "array", + "description": "Contains basic details on any Zulip messages that have been\nsent referencing this [uploaded file](/api/upload-file).\nThis includes messages sent by any user in the Zulip\norganization who sent a message containing a link to the\nuploaded file.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "date_sent": { + "type": "integer", + "description": "Time when the message was sent as a UNIX timestamp\nmultiplied by 1000 (matching the format of getTime() in JavaScript).\n\n**Changes**: Changed in Zulip 3.0 (feature level 22). This\nfield was previously strangely called `name` and was a floating\npoint number.\n" + }, + "id": { + "type": "integer", + "description": "The unique message ID. Messages should always be\ndisplayed sorted by ID.\n" + } + } + } + } + } + }, + "BasicChannel": { + "allOf": [ + { + "$ref": "#/components/schemas/BasicChannelBase" + }, + { + "additionalProperties": false, + "properties": { + "stream_id": {}, + "name": {}, + "is_archived": {}, + "description": {}, + "date_created": {}, + "creator_id": { + "nullable": true + }, + "invite_only": {}, + "rendered_description": {}, + "is_web_public": {}, + "stream_post_policy": {}, + "message_retention_days": { + "nullable": true + }, + "history_public_to_subscribers": {}, + "topics_policy": {}, + "first_message_id": { + "nullable": true + }, + "folder_id": { + "nullable": true + }, + "is_recently_active": {}, + "is_announcement_only": {}, + "can_add_subscribers_group": {}, + "can_remove_subscribers_group": {}, + "can_administer_channel_group": {}, + "can_delete_any_message_group": {}, + "can_delete_own_message_group": {}, + "can_move_messages_out_of_channel_group": {}, + "can_move_messages_within_channel_group": {}, + "can_send_message_group": {}, + "can_subscribe_group": {}, + "can_resolve_topics_group": {}, + "subscriber_count": {}, + "stream_weekly_traffic": { + "type": "integer", + "nullable": true, + "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, no information is provided on the average traffic.\nThis can be because the channel was recently created and there\nis insufficient data to make an estimate, or because the server\nwishes to omit this information for this client, this realm, or\nthis endpoint or type of event.\n\n**Changes**: New in Zulip 8.0 (feature level 199). Previously, this\nstatistic was available only in subscription objects.\n" + } + }, + "required": [ + "stream_id", + "name", + "is_archived", + "description", + "date_created", + "creator_id", + "invite_only", + "rendered_description", + "is_web_public", + "stream_post_policy", + "subscriber_count", + "message_retention_days", + "history_public_to_subscribers", + "first_message_id", + "folder_id", + "is_recently_active", + "is_announcement_only", + "can_remove_subscribers_group", + "stream_weekly_traffic", + "can_subscribe_group" + ] + } + ] + }, + "BasicChannelBase": { + "type": "object", + "description": "Object containing basic details about the channel.\n", + "properties": { + "stream_id": { + "type": "integer", + "description": "The unique ID of the channel.\n" + }, + "name": { + "type": "string", + "description": "The name of the channel.\n" + }, + "is_archived": { + "type": "boolean", + "description": "A boolean indicating whether the channel is [archived](/help/archive-a-channel).\n\n**Changes**: New in Zulip 10.0 (feature level 315).\nPreviously, this endpoint never returned archived channels.\n" + }, + "description": { + "type": "string", + "description": "The short description of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format,\nintended to be used to prepopulate UI for editing a channel's\ndescription.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "date_created": { + "type": "integer", + "description": "The UNIX timestamp for when the channel was created, in UTC seconds.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" + }, + "creator_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who created this channel.\n\nA `null` value means the channel has no recorded creator, which is often\nbecause the channel is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 9.0 (feature level 254).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "invite_only": { + "type": "boolean", + "description": "Specifies whether the channel is private or not.\nOnly people who have been invited can access a private channel.\n" + }, + "rendered_description": { + "type": "string", + "description": "The short description of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n" + }, + "is_web_public": { + "type": "boolean", + "description": "Whether the channel has been configured to allow unauthenticated\naccess to its message history from the web.\n\n**Changes**: New in Zulip 2.1.0.\n" + }, + "stream_post_policy": { + "type": "integer", + "deprecated": true, + "description": "A deprecated representation of a superset of the users who\nhave permission to post messages to the channel available\nfor backwards-compatibility. Clients should use\n`can_send_message_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can post.\n- 2 = Only administrators can post.\n- 3 = Only [full members][calc-full-member] can post.\n- 4 = Only moderators can post.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 333) and\nreplaced by `can_send_message_group`, which supports finer\nresolution of configurations, resulting in this property being\ninaccurate following that transition.\n\nNew in Zulip 3.0 (feature level 1), replacing the previous\n`is_announcement_only` boolean.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "message_retention_days": { + "type": "integer", + "nullable": true, + "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" + }, + "history_public_to_subscribers": { + "type": "boolean", + "description": "Whether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" + }, + "topics_policy": { + "$ref": "#/components/schemas/TopicsPolicy" + }, + "first_message_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the first message in the channel.\n\nIntended to help clients determine whether they need to display\nUI like the \"show all topics\" widget that would suggest the channel\nhas older history that can be accessed.\n\nIs `null` for channels with no message history.\n\n**Changes**: New in Zulip 2.1.0.\n" + }, + "folder_id": { + "$ref": "#/components/schemas/FolderId" + }, + "is_recently_active": { + "type": "boolean", + "description": "Whether the channel has recent message activity. Clients should use this to implement\n[hide inactive channels](/help/manage-inactive-channels) if\n`demote_inactive_streams` is enabled.\n\n**Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the\ndemote_inactive_streams from local message history, resulting in a choppy loading\nexperience.\n" + }, + "is_announcement_only": { + "type": "boolean", + "deprecated": true, + "description": "Whether the given channel is announcement only or not.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients\nshould use `stream_post_policy` instead.\n" + }, + "can_add_subscribers_group": { + "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" + }, + "can_remove_subscribers_group": { + "$ref": "#/components/schemas/CanRemoveSubscribersGroup" + }, + "can_administer_channel_group": { + "$ref": "#/components/schemas/CanAdministerChannelGroup" + }, + "can_delete_any_message_group": { + "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" + }, + "can_delete_own_message_group": { + "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" + }, + "can_move_messages_out_of_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" + }, + "can_move_messages_within_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" + }, + "can_send_message_group": { + "$ref": "#/components/schemas/CanSendMessageGroup" + }, + "can_subscribe_group": { + "$ref": "#/components/schemas/CanSubscribeGroup" + }, + "can_resolve_topics_group": { + "$ref": "#/components/schemas/CanResolveTopicsGroup" + }, + "subscriber_count": { + "type": "number", + "description": "The total number of non-deactivated users (including bots) who\nare subscribed to the channel. Clients are responsible for updating\nthis value using `peer_add` and `peer_remove` events.\n\nThe server's internals cannot guarantee this value is correctly\nsynced with `peer_add` and `peer_remove` events for the channel. As\na result, if a (rare) race occurs between a change in the channel's\nsubscribers and fetching this value, it is possible for a client\nthat is correctly following the events protocol to end up with a\npermanently off-by-one error in the channel's subscriber count.\n\nClients are recommended to fetch full subscriber data for a channel\nin contexts where it is important to avoid this risk. The official\nweb application, for example, uses this field primarily while\nwaiting to fetch a given channel's full subscriber list from the\nserver.\n\n**Changes**: New in Zulip 11.0 (feature level 394).\n" + } + } + }, + "BasicBot": { + "allOf": [ + { + "$ref": "#/components/schemas/BasicBotBase" + }, + { + "additionalProperties": false, + "properties": { + "user_id": {}, + "full_name": {}, + "api_key": {}, + "default_sending_stream": { + "nullable": true + }, + "default_events_register_stream": { + "nullable": true + }, + "default_all_public_streams": {}, + "avatar_url": {}, + "owner_id": { + "nullable": true + }, + "services": {}, + "is_active": { + "type": "boolean", + "description": "A boolean describing whether the user account has been deactivated.\n\n**Changes**: New in Zulip 8.0 (feature level 222). Previously\nwe sent `realm_user` event with `op` field set to `remove`\nwhen deactivating a bot and `realm_user` event with `op`\nfield set to `add` when reactivating a bot.\n" + } + } + } + ] + }, + "BasicBotBase": { + "type": "object", + "properties": { + "user_id": { + "type": "integer", + "description": "The user ID of the bot.\n" + }, + "full_name": { + "type": "string", + "description": "The full name of the bot.\n" + }, + "api_key": { + "type": "string", + "description": "The API key of the bot which it uses to make API requests.\n" + }, + "default_sending_stream": { + "type": "string", + "nullable": true, + "description": "The default sending channel of the bot. If `null`, the bot doesn't\nhave a default sending channel.\n" + }, + "default_events_register_stream": { + "type": "string", + "nullable": true, + "description": "The default channel for which the bot receives events/register data.\nIf `null`, the bot doesn't have such a default channel.\n" + }, + "default_all_public_streams": { + "type": "boolean", + "description": "Whether the bot can send messages to all channels by default.\n" + }, + "avatar_url": { + "type": "string", + "description": "The URL of the bot's avatar.\n" + }, + "owner_id": { + "type": "integer", + "nullable": true, + "description": "The user ID of the bot's owner.\n\nIf `null`, the bot has no owner.\n" + }, + "services": { + "type": "array", + "description": "An array containing extra configuration fields only relevant for\noutgoing webhook bots and embedded bots. This is always a single-element\narray.\n\nWe consider this part of the Zulip API to be unstable; it is used only\nfor UI elements for administering bots and is likely to change.\n", + "items": { + "description": "Object with extra configuration details for the bot. The fields in the\nobject depend on the type of bot.\n", + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "description": "When the bot is an outgoing webhook.\n", + "properties": { + "base_url": { + "type": "string", + "description": "The URL the outgoing webhook is configured to post to.\n" + }, + "token": { + "type": "string", + "description": "A unique token that the third-party service can use to confirm\nthat the request is indeed coming from Zulip.\n" + }, + "interface": { + "type": "integer", + "description": "An integer indicating what format requests are posted in:\n\n- 1 = Zulip's native outgoing webhook format.\n- 2 = Emulate the Slack outgoing webhook format.\n" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "description": "When the bot is an embedded bot.\n", + "properties": { + "service_name": { + "type": "string", + "description": "The name of the bot.\n" + }, + "config_data": { + "$ref": "#/components/schemas/BotConfiguration" + } + } + } + ] + } + } + } + }, + "Bot": { + "allOf": [ + { + "$ref": "#/components/schemas/BasicBotBase" + }, + { + "description": "Object containing details of a bot.\n", + "additionalProperties": false, + "properties": { + "user_id": {}, + "full_name": {}, + "api_key": {}, + "default_sending_stream": { + "nullable": true + }, + "default_events_register_stream": { + "nullable": true + }, + "default_all_public_streams": {}, + "avatar_url": {}, + "owner_id": { + "nullable": true + }, + "services": {}, + "email": { + "type": "string", + "description": "The email of the bot.\n" + }, + "bot_type": { + "type": "integer", + "nullable": true, + "description": "An integer describing the type of bot:\n\n- `1` for a `Generic` bot.\n- `2` for an `Incoming webhook` bot.\n- `3` for an `Outgoing webhook` bot.\n- `4` for an `Embedded` bot.\n" + }, + "is_active": { + "type": "boolean", + "description": "A boolean describing whether the user account has been deactivated.\n" + } + } + } + ] + }, + "BotConfiguration": { + "type": "object", + "description": "A dictionary of string key/value pairs, which describe the configuration\nfor the bot. These are usually details like API keys, and are unique to\nthe integration/bot. Can be an empty dictionary.\n", + "additionalProperties": { + "description": "`{config_key}`: Description/value of the configuration data key.\n", + "type": "string" + } + }, + "WebhookConfigOption": { + "type": "array", + "description": "An array of configuration options that can be set when creating\na bot user for this incoming webhook integration.\n\nThis is an unstable API. Please discuss in chat.zulip.org before\nusing it.\n\n**Changes**: As of Zulip 11.0 (feature level 403), this\nobject is reserved for integration-specific configuration options\nthat can be set when creating a bot user. Previously, this object\nalso included optional webhook URL parameters, which are now\nspecified in the `url_options` object.\n\nBefore Zulip 10.0 (feature level 318), this field was named `config`,\nand was reserved for configuration data key-value pairs.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "description": "A key for the configuration option.\n" + }, + "label": { + "type": "string", + "description": "A human-readable label of the configuration option.\n" + }, + "validator": { + "type": "string", + "description": "The name of the validator function for the configuration\noption.\n" + } + } + } + }, + "WebhookUrlOption": { + "type": "array", + "description": "An array of optional URL parameter options for the incoming webhook\nintegration. In the web app, these are used when\n[generating a URL for an integration](/help/generate-integration-url).\n\nThis is an unstable API expected to be used only by the Zulip web\napp. Please discuss in chat.zulip.org before using it.\n\n**Changes**: New in Zulip 11.0 (feature level 403). Previously,\nthese optional URL parameter options were included in the\n`config_options` object.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "description": "The parameter variable to encode the users input for this\noption in the integrations webhook URL.\n" + }, + "label": { + "type": "string", + "description": "A human-readable label of the url option.\n" + }, + "validator": { + "type": "string", + "description": "The name of the validator function for the configuration\noption.\n" + } + } + } + }, + "CustomProfileField": { + "type": "object", + "additionalProperties": false, + "description": "Dictionary containing the details of a custom profile field configured\nfor this organization.\n", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the custom profile field. This will be referenced in the custom\nprofile fields section of user objects.\n" + }, + "type": { + "type": "integer", + "description": "An integer indicating the type of the custom profile field, which determines\nhow it is configured and displayed to users.\n\nSee the [Custom profile fields](/help/custom-profile-fields#profile-field-types)\narticle for details on what each type means.\n\n- **1**: Short text\n- **2**: Long text\n- **3**: List of options\n- **4**: Date picker\n- **5**: Link\n- **6**: Person picker\n- **7**: External account\n- **8**: Pronouns\n\n**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).\n" + }, + "order": { + "type": "integer", + "description": "Custom profile fields are displayed in both settings UI and\nUI showing users' profiles in increasing `order`.\n" + }, + "name": { + "type": "string", + "description": "The name of the custom profile field.\n" + }, + "hint": { + "type": "string", + "description": "The help text to be displayed for the custom profile field in user-facing\nsettings UI for configuring custom profile fields.\n" + }, + "field_data": { + "type": "string", + "description": "Field types 3 (List of options) and 7 (External account) support storing\nadditional configuration for the field type in the `field_data` attribute.\n\nFor field type 3 (List of options), this attribute is a JSON dictionary\ndefining the choices and the order they will be displayed in the\ndropdown UI for individual users to select an option.\n\nThe interface for field type 7 is not yet stabilized.\n" + }, + "display_in_profile_summary": { + "type": "boolean", + "description": "Whether the custom profile field, display or not on the user card.\n\nCurrently it's value not allowed to be `true` of `Long text` and `Person picker`\n[profile field types](/help/custom-profile-fields#profile-field-types).\n\nThis field is only included when its value is `true`.\n\n**Changes**: New in Zulip 6.0 (feature level 146).\n", + "default": false + }, + "required": { + "type": "boolean", + "description": "Whether an organization administrator has configured this profile field as\nrequired.\n\nBecause the required property is mutable, clients cannot assume that a required\ncustom profile field has a value. The Zulip web application displays a prominent\nbanner to any user who has not set a value for a required field.\n\n**Changes**: New in Zulip 9.0 (feature level 244).\n" + }, + "editable_by_user": { + "type": "boolean", + "description": "Whether regular users can edit this profile field on their own account.\n\nNote that organization administrators can edit custom profile fields for any user\nregardless of this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 296).\n", + "default": true + } + }, + "required": [ + "id", + "type", + "order", + "name", + "hint", + "required", + "editable_by_user" + ] + }, + "OnboardingStep": { + "type": "object", + "additionalProperties": false, + "description": "Dictionary containing details of a single onboarding step.\n", + "properties": { + "type": { + "type": "string", + "description": "The type of the onboarding step. Valid value is `\"one_time_notice\"`.\n\n**Changes**: Removed type `\"hotspot\"` in Zulip 9.0 (feature level 259).\n\nNew in Zulip 8.0 (feature level 233).\n" + }, + "name": { + "type": "string", + "description": "The name of the onboarding step.\n" + } + } + }, + "RealmAuthenticationMethod": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Boolean describing whether the authentication method (i.e. its key)\nis enabled in this organization.\n" + }, + "available": { + "type": "boolean", + "description": "Boolean describing whether the authentication method is available for use.\nIf false, the organization is not eligible to enable the authentication\nmethod.\n" + }, + "unavailable_reason": { + "type": "string", + "description": "Reason why the authentication method is unavailable. This field is optional\nand is only present when 'available' is false.\n" + } + }, + "additionalProperties": false, + "description": "Dictionary describing the properties of an authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n" + }, + "RealmEmoji": { + "type": "object", + "additionalProperties": false, + "description": "`{emoji_id}`: Object containing details about the emoji with\nthe specified ID. It has the following properties:\n", + "properties": { + "id": { + "type": "string", + "description": "The ID for this emoji, same as the object's key.\n" + }, + "name": { + "type": "string", + "description": "The user-friendly name for this emoji. Users in the organization\ncan use this emoji by writing this name between colons (`:name :`).\n" + }, + "source_url": { + "type": "string", + "description": "The path relative to the organization's URL where the\nemoji's image can be found.\n" + }, + "still_url": { + "type": "string", + "nullable": true, + "description": "Only non-null when the emoji's image is animated.\n\nThe path relative to the organization's URL where a still\n(not animated) version of the emoji can be found. (This is\ncurrently always the first frame of the animation).\n\nThis is useful for clients to display the emoji in contexts\nwhere continuously animating it would be a bad user experience\n(E.g. because it would be distracting).\n\n**Changes**: New in Zulip 5.0 (added as optional field in\nfeature level 97 and then made mandatory, but nullable, in\nfeature level 113).\n" + }, + "deactivated": { + "type": "boolean", + "description": "Whether the emoji has been deactivated or not.\n" + }, + "author_id": { + "type": "integer", + "nullable": true, + "description": "The user ID of the user who uploaded the custom emoji.\nWill be `null` if the uploader is unknown.\n\n**Changes**: New in Zulip 3.0 (feature level 7). Previously\nwas accessible via an `author` object with an `id` field.\n" + } + } + }, + "RealmDomain": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of the newly added domain.\n", + "properties": { + "domain": { + "type": "string", + "description": "The new allowed domain.\n" + }, + "allow_subdomains": { + "type": "boolean", + "description": "Whether subdomains are allowed for this domain.\n" + } + } + }, + "RealmPlayground": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details about a realm playground.\n", + "properties": { + "id": { + "type": "integer", + "description": "The unique ID for the realm playground.\n" + }, + "name": { + "type": "string", + "description": "The user-visible display name of the playground. Clients\nshould display this in UI for picking which playground to\nopen a code block in, to differentiate between multiple\nconfigured playground options for a given pygments\nlanguage.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n" + }, + "pygments_language": { + "type": "string", + "description": "The name of the Pygments language lexer for that\nprogramming language.\n" + }, + "url_template": { + "type": "string", + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template for the playground. The template contains\nexactly one variable named `code`, which determines how the\nextracted code should be substituted in the playground URL.\n\n**Changes**: New in Zulip 8.0 (feature level 196). This replaced the\n`url_prefix` parameter, which was used to construct URLs by just\nconcatenating url_prefix and code.\n" + } + } + }, + "RealmExport": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details about a\n[data export](/help/export-your-organization).\n", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the data export.\n" + }, + "acting_user_id": { + "type": "integer", + "description": "The ID of the user who created the data export.\n" + }, + "export_time": { + "type": "number", + "description": "The UNIX timestamp of when the data export was started.\n" + }, + "deleted_timestamp": { + "type": "number", + "nullable": true, + "description": "The UNIX timestamp of when the data export was deleted.\n\nWill be `null` if the data export has not been deleted.\n" + }, + "failed_timestamp": { + "type": "number", + "nullable": true, + "description": "The UNIX timestamp of when the data export failed.\n\nWill be `null` if the data export succeeded, or if it's\nstill being generated.\n" + }, + "export_url": { + "type": "string", + "nullable": true, + "description": "The URL to download the generated data export.\n\nWill be `null` if the data export failed, or if it's\nstill being generated.\n" + }, + "pending": { + "type": "boolean", + "description": "Whether the data export is pending, which indicates it\nis still being generated, or if it succeeded, failed or\nwas deleted before being generated.\n\nDepending on the size of the organization, it can take\nanywhere from seconds to an hour to generate the data\nexport.\n" + }, + "export_type": { + "type": "integer", + "description": "Whether the data export is a public or a standard data export.\n\n- 1 = Public data export.\n- 2 = Standard data export.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nthe export type was not included in these objects because only\npublic data exports could be created or listed via the API or UI.\n" + } + } + }, + "UserGroup": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the user group's attributes.\n", + "properties": { + "name": { + "type": "string", + "description": "The name of the user group.\n" + }, + "date_created": { + "type": "integer", + "nullable": true, + "description": "The UNIX timestamp for when the user group was created, in UTC seconds.\n\nA `null` value means the user group has no recorded date, which is often\nbecause the user group is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "creator_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who created this user group.\n\nA `null` value means the user group has no recorded creator, which is often\nbecause the user group is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "description": { + "type": "string", + "description": "The description of the user group.\n" + }, + "members": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the ID of the users who are\nmembers of this user group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this\nlist also included deactivated users who were members of\nthe user group before being deactivated.\n" + }, + "direct_subgroup_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Array containing the ID of the direct_subgroups of\nthis user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nIntroduced in feature level 127 as `subgroups`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the user group.\n" + }, + "is_system_group": { + "type": "boolean", + "description": "Whether the user group is a system group which cannot be\ndirectly modified by users.\n\n**Changes**: New in Zulip 5.0 (feature level 93).\n" + }, + "can_add_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_join_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_leave_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "can_manage_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" + } + ] + }, + "can_mention_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" + } + ] + }, + "can_remove_members_group": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "deactivated": { + "type": "boolean", + "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" + } + } + }, + "GroupSettingValue": { + "oneOf": [ + { + "type": "integer", + "description": "The ID of the [user group](/help/user-groups) with this permission.\n" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "direct_members": { + "description": "The list of IDs of individual users in the collection of users with this permission.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this list would include\ndeactivated users who had the permission before being deactivated.\n", + "type": "array", + "items": { + "type": "integer" + } + }, + "direct_subgroups": { + "description": "The list of IDs of the groups in the collection of users with this permission.\n", + "type": "array", + "items": { + "type": "integer" + } + } + }, + "description": "An object with these fields:\n" + } + ] + }, + "GroupSettingValueUpdate": { + "type": "object", + "additionalProperties": false, + "properties": { + "new": { + "allOf": [ + { + "description": "The new [group-setting value](/api/group-setting-values) for who would\nhave this permission.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + }, + "old": { + "allOf": [ + { + "description": "The expected current [group-setting value](/api/group-setting-values)\nfor who has this permission.\n" + }, + { + "$ref": "#/components/schemas/GroupSettingValue" + } + ] + } + }, + "required": ["new"] + }, + "Invite": { + "type": "object", + "description": "A dictionary containing details about an [invitation](/help/invite-new-users).\n", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "The ID of the invitation.\n\nNote that email invitations and reusable invitation links are stored\nin different database tables on the server, so each ID is guaranteed\nto be unique in combination with the boolean value of `is_multiuse`,\ne.g. there can only be one invitation with `id: 1` and `is_multiuse:\ntrue`.\n" + }, + "invited_by_user_id": { + "type": "integer", + "description": "The [user ID](/api/get-user) of the user who created the invitation.\n\n**Changes**: New in Zulip 3.0 (feature level 22), replacing the `ref`\nfield which contained the Zulip display email address of the user who\ncreated the invitation.\n" + }, + "invited": { + "type": "integer", + "description": "The UNIX timestamp for when the invitation was created, in UTC seconds.\n" + }, + "expiry_date": { + "type": "integer", + "nullable": true, + "description": "The UNIX timestamp for when the invitation will expire, in UTC seconds.\nIf `null`, the invitation never expires.\n" + }, + "invited_as": { + "type": "integer", + "enum": [100, 200, 300, 400, 600], + "description": "The [organization-level role](/api/roles-and-permissions) of the user that\nis created when the invitation is accepted.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n" + }, + "email": { + "type": "string", + "description": "The email address the invitation was sent to. This will not be present when\n`is_multiuse` is `true` (i.e. the invitation is a reusable invitation link).\n" + }, + "notify_referrer_on_join": { + "type": "boolean", + "description": "A boolean indicating whether the referrer has opted to receive a direct\nmessage from [notification bot](/help/configure-automated-notices) when a user\naccount is created using this invitation.\n\n**Changes**: New in Zulip 9.0 (feature level 267). Previously,\nreferrers always received such direct messages.\n" + }, + "link_url": { + "type": "string", + "description": "The URL of the reusable invitation link. This will not be present when\n`is_multiuse` is `false` (i.e. the invitation is an email invitation).\n" + }, + "is_multiuse": { + "type": "boolean", + "description": "A boolean specifying whether the [invitation](/help/invite-new-users) is a\nreusable invitation link or an email invitation.\n" + } + } + }, + "InviteExpirationParameter": { + "description": "The number of minutes before the invitation will expire. If `null`, the\ninvitation will never expire. If unspecified, the server will use a default\nvalue (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which\ndefaults to 14400, i.e. 10 days) for when the invitation will expire.\n\n**Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an\n`invite_expires_in_days` parameter, which specified the duration in days instead\nof minutes.\n", + "type": "integer", + "nullable": true, + "example": 14400 + }, + "InviteRoleParameter": { + "description": "The [organization-level role](/api/roles-and-permissions) of the user that is\ncreated when the invitation is accepted.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\nUsers can only create invitation links for\n[roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels)\nas their own. For example, a moderator cannot invite someone to be an owner\nor administrator, but they can invite them to be a moderator or member.\n\n**Changes**: In Zulip 4.0 (feature level 61), added support for inviting\nusers as moderators.\n", + "type": "integer", + "enum": [100, 200, 300, 400, 600], + "default": 400, + "example": 600 + }, + "Subscription": { + "type": "object", + "additionalProperties": false, + "properties": { + "stream_id": { + "type": "integer", + "description": "The unique ID of a channel.\n" + }, + "name": { + "type": "string", + "description": "The name of a channel.\n" + }, + "description": { + "type": "string", + "description": "The [description](/help/change-the-channel-description) of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format,\nintended to be used to prepopulate UI for editing a channel's\ndescription.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n\nSee also `rendered_description`.\n" + }, + "rendered_description": { + "type": "string", + "description": "The [description](/help/change-the-channel-description) of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n\nSee also `description`.\n" + }, + "date_created": { + "type": "integer", + "description": "The UNIX timestamp for when the channel was created, in UTC seconds.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" + }, + "creator_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who created this channel.\n\nA `null` value means the channel has no recorded creator, which is often\nbecause the channel is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 9.0 (feature level 254).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" + }, + "invite_only": { + "type": "boolean", + "description": "Specifies whether the channel is private or not.\nOnly people who have been invited can access a private channel.\n" + }, + "subscribers": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "A list of user IDs of users who are also subscribed\nto a given channel. Included only if `include_subscribers` is `true`.\n" + }, + "partial_subscribers": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "If [`include_subscribers=\"partial\"`](/api/get-subscriptions#parameter-include_subscribers)\nwas requested, the server may, at its discretion, send a\n`partial_subscribers` list rather than a `subscribers` list\nfor channels with a large number of subscribers.\n\nThe `partial_subscribers` list contains an arbitrary\nsubset of the channel's subscribers that is guaranteed\nto include all bot user subscribers as well as all\nusers who have been active in the last 14 days, but\notherwise can be chosen arbitrarily by the server.\n\n**Changes**: New in Zulip 11.0 (feature level 412).\n" + }, + "desktop_notifications": { + "type": "boolean", + "nullable": true, + "description": "A boolean specifying whether desktop notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_desktop_notifications`, for\nthis channel.\n" + }, + "email_notifications": { + "type": "boolean", + "nullable": true, + "description": "A boolean specifying whether email notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_email_notifications`, for\nthis channel.\n" + }, + "wildcard_mentions_notify": { + "type": "boolean", + "nullable": true, + "description": "A boolean specifying whether wildcard mentions\ntrigger notifications as though they were personal\nmentions in this channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, wildcard_mentions_notify, for\nthis channel.\n" + }, + "push_notifications": { + "type": "boolean", + "nullable": true, + "description": "A boolean specifying whether push notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_push_notifications`, for\nthis channel.\n" + }, + "audible_notifications": { + "type": "boolean", + "nullable": true, + "description": "A boolean specifying whether audible notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_audible_notifications`, for\nthis channel.\n" + }, + "pin_to_top": { + "type": "boolean", + "description": "A boolean specifying whether the given channel has been pinned\nto the top.\n" + }, + "is_muted": { + "type": "boolean", + "description": "Whether the user has muted the channel. Muted channels do\nnot count towards your total unread count and do not show\nup in the `Combined feed` view (previously known as `All messages`).\n\n**Changes**: Prior to Zulip 2.1.0, this feature was\nrepresented by the more confusingly named `in_home_view` (with the\nopposite value, `in_home_view=!is_muted`).\n" + }, + "in_home_view": { + "type": "boolean", + "deprecated": true, + "description": "Legacy property for if the given channel is muted, with inverted meaning.\n\n**Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted`\nwhere available.\n" + }, + "is_announcement_only": { + "type": "boolean", + "deprecated": true, + "description": "Whether only organization administrators can post to the channel.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients\nshould use `stream_post_policy` instead.\n" + }, + "is_web_public": { + "type": "boolean", + "description": "Whether the channel has been configured to allow unauthenticated\naccess to its message history from the web.\n" + }, + "color": { + "type": "string", + "description": "The user's personal color for the channel.\n" + }, + "stream_post_policy": { + "type": "integer", + "deprecated": true, + "description": "A deprecated representation of a superset of the users who\nhave permission to post messages to the channel available\nfor backwards-compatibility. Clients should use\n`can_send_message_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can post.\n- 2 = Only administrators can post.\n- 3 = Only [full members][calc-full-member] can post.\n- 4 = Only moderators can post.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 333) and\nreplaced by `can_send_message_group`, which supports finer\nresolution of configurations, resulting in this property being\ninaccurate following that transition.\n\nNew in Zulip 3.0 (feature level 1), replacing the previous\n`is_announcement_only` boolean.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" + }, + "message_retention_days": { + "type": "integer", + "nullable": true, + "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" + }, + "history_public_to_subscribers": { + "type": "boolean", + "description": "Whether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" + }, + "first_message_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the first message in the channel.\n\nIntended to help clients determine whether they need to display\nUI like the \"show all topics\" widget that would suggest the channel\nhas older history that can be accessed.\n\nIs `null` for channels with no message history.\n" + }, + "folder_id": { + "$ref": "#/components/schemas/FolderId" + }, + "topics_policy": { + "$ref": "#/components/schemas/TopicsPolicy" + }, + "is_recently_active": { + "type": "boolean", + "description": "Whether the channel has recent message activity. Clients should use this to implement\n[hiding inactive channels](/help/manage-inactive-channels).\n\n**Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the\ndemote_inactive_streams from local message history, resulting in a choppy loading\nexperience.\n" + }, + "stream_weekly_traffic": { + "type": "integer", + "nullable": true, + "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, the channel was recently created and there is\ninsufficient data to estimate the average traffic.\n" + }, + "can_add_subscribers_group": { + "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" + }, + "can_remove_subscribers_group": { + "$ref": "#/components/schemas/CanRemoveSubscribersGroup" + }, + "can_administer_channel_group": { + "$ref": "#/components/schemas/CanAdministerChannelGroup" + }, + "can_delete_any_message_group": { + "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" + }, + "can_delete_own_message_group": { + "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" + }, + "can_move_messages_out_of_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" + }, + "can_move_messages_within_channel_group": { + "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" + }, + "can_send_message_group": { + "$ref": "#/components/schemas/CanSendMessageGroup" + }, + "can_subscribe_group": { + "$ref": "#/components/schemas/CanSubscribeGroup" + }, + "can_resolve_topics_group": { + "$ref": "#/components/schemas/CanResolveTopicsGroup" + }, + "is_archived": { + "type": "boolean", + "description": "A boolean indicating whether the channel is [archived](/help/archive-a-channel).\n\n**Changes**: New in Zulip 10.0 (feature level 315).\nPreviously, subscriptions only included active\nchannels. Note that some endpoints will never return archived\nchannels unless the client declares explicit support for\nthem via the `archived_channels` client capability.\n" + }, + "subscriber_count": { + "type": "number", + "description": "The total number of non-deactivated users (including bots) who\nare subscribed to the channel. Clients are responsible for updating\nthis value using `peer_add` and `peer_remove` events.\n\nThe server's internals cannot guarantee this value is correctly\nsynced with `peer_add` and `peer_remove` events for the channel. As\na result, if a (rare) race occurs between a change in the channel's\nsubscribers and fetching this value, it is possible for a client\nthat is correctly following the events protocol to end up with a\npermanently off-by-one error in the channel's subscriber count.\n\nClients are recommended to fetch full subscriber data for a channel\nin contexts where it is important to avoid this risk. The official\nweb application, for example, uses this field primarily while\nwaiting to fetch a given channel's full subscriber list from the\nserver.\n\n**Changes**: New in Zulip 11.0 (feature level 394).\n" + } + } + }, + "DefaultChannelGroup": { + "type": "object", + "description": "Dictionary containing details of a default channel\ngroup.\n", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "Name of the default channel group.\n" + }, + "description": { + "type": "string", + "description": "Description of the default channel group.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the default channel group.\n" + }, + "streams": { + "type": "array", + "description": "An array of IDs of all the channels in the default stream group.\n\n**Changes**: Before Zulip 10.0 (feature level 330), we sent array\nof dictionaries where each dictionary contained details about a\nsingle stream in the default stream group.\n", + "items": { + "type": "integer" + } + } + } + }, + "EmailAddressVisibility": { + "type": "integer", + "description": "The [policy][permission-level] for [which other users][help-email-visibility]\nin this organization can see the user's real email address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n" + }, + "EmojiReaction": { + "allOf": [ + { + "$ref": "#/components/schemas/EmojiBase" + }, + { + "additionalProperties": false, + "properties": { + "emoji_code": {}, + "emoji_name": {}, + "reaction_type": {}, + "user_id": { + "type": "integer", + "description": "The ID of the user who added the reaction.\n\n**Changes**: New in Zulip 3.0 (feature level 2). The `user`\nobject is deprecated and will be removed in the future.\n\nIn Zulip 10.0 (feature level 328), the deprecated `user` object\nwas removed which contained the following properties: `id`, `email`,\n`full_name` and `is_mirror_dummy`.\n" + } + } + } + ] + }, + "EmojiBase": { + "type": "object", + "properties": { + "emoji_name": { + "type": "string", + "description": "Name of the emoji.\n" + }, + "emoji_code": { + "type": "string", + "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n" + }, + "reaction_type": { + "type": "string", + "enum": ["unicode_emoji", "realm_emoji", "zulip_extra_emoji"], + "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n" + } + } + }, + "EmojiReactionEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/EmojiBase" + }, + { + "properties": { + "user_id": { + "type": "integer", + "description": "The ID of the user who added the reaction.\n\n**Changes**: New in Zulip 3.0 (feature level 2). The `user`\nobject is deprecated and will be removed in the future.\n" + }, + "user": { + "type": "object", + "additionalProperties": false, + "deprecated": true, + "description": "Dictionary with data on the user who added the\nreaction, including the user ID as the `user_id`\nfield.\n\n**Changes**: This field was re-added in Zulip 10.0 (feature\nlevel 339) after having been removed in Zulip 10.0 (feature\nlevel 328). It remains deprecated; it was re-added because the\nReact Native mobile app was still using it.\n\n**Deprecated** and to be removed in a future release once core\nclients have migrated to use the adjacent `user_id` field, which\nwas introduced in Zulip 3.0 (feature level 2). Clients\nsupporting older Zulip server versions should use the user ID\nmentioned in the description above as they would the `user_id`\nfield.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "ID of the user.\n" + }, + "email": { + "type": "string", + "description": "Zulip API email of the user.\n" + }, + "full_name": { + "type": "string", + "description": "Full name of the user.\n" + }, + "is_mirror_dummy": { + "type": "boolean", + "description": "Whether the user is a mirror dummy.\n" + } + } + } + } + } + ] + }, + "MessagesEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/MessagesBase" + }, + { + "additionalProperties": false, + "properties": { + "avatar_url": { + "nullable": true + }, + "client": {}, + "content": {}, + "content_type": {}, + "display_recipient": {}, + "edit_history": {}, + "id": {}, + "is_me_message": {}, + "last_edit_timestamp": {}, + "last_moved_timestamp": {}, + "reactions": {}, + "recipient_id": {}, + "sender_email": {}, + "sender_full_name": {}, + "sender_id": {}, + "sender_realm_str": {}, + "stream_id": {}, + "subject": {}, + "submessages": {}, + "timestamp": {}, + "topic_links": {}, + "type": {} + } + } + ] + }, + "MessagesBase": { + "type": "object", + "description": "Object containing details of the message.\n", + "properties": { + "avatar_url": { + "type": "string", + "nullable": true, + "description": "The URL of the message sender's avatar. Can be `null` only if\nthe current user has access to the sender's real email address\nand `client_gravatar` was `true`.\n\nIf `null`, then the sender has not uploaded an avatar in Zulip,\nand the client can compute the gravatar URL by hashing the\nsender's email address, which corresponds in this case to their\nreal email address.\n\n**Changes**: Before Zulip 7.0 (feature level 163), access to a\nuser's real email address was a realm-level setting. As of this\nfeature level, `email_address_visibility` is a user setting.\n" + }, + "client": { + "type": "string", + "description": "A Zulip \"client\" string, describing what Zulip client\nsent the message.\n" + }, + "content": { + "type": "string", + "description": "The content/body of the message.\nWhen `apply_markdown` is set, it will be in HTML format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "content_type": { + "type": "string", + "description": "The HTTP `content_type` for the message content. This\nwill be `text/html` or `text/x-markdown`, depending on\nwhether `apply_markdown` was set.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n" + }, + "display_recipient": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "ID of the user.\n" + }, + "email": { + "type": "string", + "description": "Zulip API email of the user.\n" + }, + "full_name": { + "type": "string", + "description": "Full name of the user.\n" + }, + "is_mirror_dummy": { + "type": "boolean", + "description": "Whether the user is a mirror dummy.\n" + } + } + } + } + ], + "description": "Data on the recipient of the message;\neither the name of a channel or a dictionary containing basic data on\nthe users who received the message.\n" + }, + "edit_history": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "prev_content": { + "type": "string", + "description": "Only present if message's content was edited.\n\nThe content of the message immediately prior to this\nedit event.\n" + }, + "prev_rendered_content": { + "type": "string", + "description": "Only present if message's content was edited.\n\nThe rendered HTML representation of `prev_content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "prev_stream": { + "type": "integer", + "description": "Only present if message's channel was edited.\n\nThe channel ID of the message immediately prior to this\nedit event.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n" + }, + "prev_topic": { + "type": "string", + "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately prior to this\nedit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\nPreviously, this field was called `prev_subject`;\nclients are recommended to rename `prev_subject` to\n`prev_topic` if present for compatibility with\nolder Zulip servers.\n" + }, + "stream": { + "type": "integer", + "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message\nimmediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" + }, + "timestamp": { + "type": "integer", + "description": "The UNIX timestamp for the edit.\n" + }, + "topic": { + "type": "string", + "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" + }, + "user_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user that made the edit.\n\nWill be `null` only for edit history\nevents predating March 2017.\n\nClients can display edit history events where this\nis `null` as modified by either the sender (for content\nedits) or an unknown user (for topic edits).\n" + } + }, + "required": ["user_id", "timestamp"] + }, + "description": "An array of objects, with each object documenting the\nchanges in a previous edit made to the message,\nordered chronologically from most recent to least recent\nedit.\n\nNot present if the message has never been edited or moved,\nor if [viewing message edit history][edit-history-access]\nis not allowed in the organization.\n\nEvery object will contain `user_id` and `timestamp`.\n\nThe other fields are optional, and will be present or not\ndepending on whether the channel, topic, and/or message\ncontent were modified in the edit event. For example, if\nonly the topic was edited, only `prev_topic` and `topic`\nwill be present in addition to `user_id` and `timestamp`.\n\n[edit-history-access]: /help/restrict-message-edit-history-access\n\n**Changes**: In Zulip 10.0 (feature level 284), removed the\n`prev_rendered_content_version` field as it is an internal\nserver implementation detail not used by any client.\n" + }, + "id": { + "type": "integer", + "description": "The unique message ID. Messages should always be\ndisplayed sorted by ID.\n" + }, + "is_me_message": { + "type": "boolean", + "description": "Whether the message is a [/me status message][status-messages]\n\n[status-messages]: /help/format-your-message-using-markdown#status-messages\n" + }, + "last_edit_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message's content was last edited, in\nUTC seconds.\n\nNot present if the message's content has never been edited.\n\nClients should use this field, rather than parsing the `edit_history`\narray, to display an indicator that the message has been edited.\n\n**Changes**: Prior to Zulip 10.0 (feature level 365), this was the\ntime when the message was last edited or moved.\n" + }, + "last_moved_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message was last moved to a different\nchannel or topic, in UTC seconds.\n\nNot present if the message has never been moved, or if the only topic\nmoves for the message are [resolving or unresolving](/help/resolve-a-topic)\nthe message's topic.\n\nClients should use this field, rather than parsing the `edit_history`\narray, to display an indicator that the message has been moved.\n\n**Changes**: New in Zulip 10.0 (feature level 365). Previously,\nparsing the `edit_history` array was required in order to correctly\ndisplay moved message indicators.\n" + }, + "reactions": { + "type": "array", + "description": "Data on any reactions to the message.\n", + "items": { + "$ref": "#/components/schemas/EmojiReaction" + } + }, + "recipient_id": { + "type": "integer", + "description": "A unique ID for the set of users receiving the\nmessage (either a channel or group of users). Useful primarily\nfor hashing.\n\n**Changes**: Before Zulip 10.0 (feature level 327), `recipient_id`\nwas the same across all incoming 1:1 direct messages. Now, each\nincoming message uniquely shares a `recipient_id` with outgoing\nmessages in the same conversation.\n" + }, + "sender_email": { + "type": "string", + "description": "The Zulip API email address of the message's sender.\n" + }, + "sender_full_name": { + "type": "string", + "description": "The full name of the message's sender.\n" + }, + "sender_id": { + "type": "integer", + "description": "The user ID of the message's sender.\n" + }, + "sender_realm_str": { + "type": "string", + "description": "A string identifier for the realm the sender is in. Unique only within\nthe context of a given Zulip server.\n\nE.g. on `example.zulip.com`, this will be `example`.\n" + }, + "stream_id": { + "type": "integer", + "description": "Only present for channel messages; the ID of the channel.\n" + }, + "subject": { + "type": "string", + "description": "The `topic` of the message. Currently always `\"\"` for direct messages,\nthough this could change if Zulip adds support for topics in direct\nmessage conversations.\n\nThe field name is a legacy holdover from when topics were\ncalled \"subjects\" and will eventually change.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nthe empty string value is replaced with the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response, for channel messages.\n\n**Changes**: Before Zulip 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" + }, + "submessages": { + "type": "array", + "description": "Data used for certain experimental Zulip integrations.\n", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "msg_type": { + "type": "string", + "description": "The type of the message.\n" + }, + "content": { + "type": "string", + "description": "The new content of the submessage.\n" + }, + "message_id": { + "type": "integer", + "description": "The ID of the message to which the submessage has been added.\n" + }, + "sender_id": { + "type": "integer", + "description": "The ID of the user who sent the message.\n" + }, + "id": { + "type": "integer", + "description": "The ID of the submessage.\n" + } + } + } + }, + "timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message was sent,\nin UTC seconds.\n" + }, + "topic_links": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "text": { + "type": "string", + "description": "The original link text present in the topic.\n" + }, + "url": { + "type": "string", + "description": "The expanded target url which the link points to.\n" + } + } + }, + "description": "Data on any links to be included in the `topic`\nline (these are generated by [custom linkification\nfilters](/help/add-a-custom-linkifier) that match content in the\nmessage's topic.)\n\n**Changes**: This field contained a list of urls before\nZulip 4.0 (feature level 46).\n\nNew in Zulip 3.0 (feature level 1). Previously, this field was called\n`subject_links`; clients are recommended to rename `subject_links` to `topic_links`\nif present for compatibility with older Zulip servers.\n" + }, + "type": { + "type": "string", + "description": "The type of the message: `\"stream\"` or `\"private\"`.\n" + } + } + }, + "ModernPresenceFormat": { + "type": "object", + "description": "`{user_id}`: Presence data (modern format) for the user with\nthe specified ID.\n", + "additionalProperties": false, + "properties": { + "active_timestamp": { + "type": "integer", + "description": "The UNIX timestamp of the last time a client connected\nto Zulip reported that the user was actually present\n(e.g. via focusing a browser window or interacting\nwith a computer running the desktop app).\n\nClients should display users with a current\n`active_timestamp` as fully present.\n" + }, + "idle_timestamp": { + "type": "integer", + "description": "The UNIX timestamp of the last time the user had a\nclient connected to Zulip, including idle clients\nwhere the user hasn't interacted with the system\nrecently.\n\nThe Zulip server has no way of distinguishing whether\nan idle web app user is at their computer, but hasn't\ninteracted with the Zulip tab recently, or simply left\ntheir desktop computer on when they left.\n\nThus, clients should display users with a current\n`idle_timestamp` but no current `active_timestamp` as\npotentially present.\n" + } + } + }, + "LegacyPresenceFormat": { + "type": "object", + "description": "`{client_name}` or `\"aggregated\"`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will always\ncontain two keys, `\"website\"` and `\"aggregated\"`, with identical data. The\nserver no longer stores which client submitted presence updates.\n\nPreviously, the `{client_name}` keys for these objects were the names of the\ndifferent clients where the user was logged in, for example `website` or\n`ZulipDesktop`.\n", + "additionalProperties": false, + "properties": { + "client": { + "type": "string", + "description": "The client's platform name.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will\nalways be `\"website\"` as the server no longer stores which client\nsubmitted presence data.\n" + }, + "status": { + "type": "string", + "enum": ["idle", "active"], + "description": "The status of the user on this client. Will be either `\"idle\"`\nor `\"active\"`.\n" + }, + "timestamp": { + "type": "integer", + "description": "The UNIX timestamp of when this client sent the user's presence\nto the server with the precision of a second.\n" + }, + "pushable": { + "type": "boolean", + "description": "Whether the client is capable of showing mobile/push notifications\nto the user.\n\nNot present in objects with the `\"aggregated\"` key.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), always\n`false` when present as the server no longer stores which client\nsubmitted presence data.\n" + } + } + }, + "UserStatus": { + "type": "object", + "additionalProperties": false, + "properties": { + "away": { + "type": "boolean", + "deprecated": true, + "description": "If present, the user has marked themself \"away\".\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n" + }, + "status_text": { + "type": "string", + "description": "If present, the text content of the user's status message.\n" + }, + "emoji_name": { + "type": "string", + "description": "If present, the name for the emoji to associate with the user's status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + }, + "emoji_code": { + "type": "string", + "description": "If present, a unique identifier, defining the specific emoji codepoint\nrequested, within the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + }, + "reaction_type": { + "type": "string", + "enum": ["unicode_emoji", "realm_emoji", "zulip_extra_emoji"], + "description": "If present, a string indicating the type of emoji. Each emoji\n`reaction_type` has an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" + } + } + }, + "Draft": { + "type": "object", + "description": "A dictionary for representing a message draft.\n", + "properties": { + "id": { + "type": "integer", + "description": "The unique ID of the draft. It will only used whenever the drafts are\nfetched. This field should not be specified when the draft is being\ncreated or edited.\n" + }, + "type": { + "type": "string", + "description": "The type of the draft. Either unaddressed (empty string), `\"stream\"`,\nor `\"private\"` (for one-on-one and group direct messages).\n", + "enum": ["", "stream", "private"] + }, + "to": { + "type": "array", + "description": "An array of the tentative target audience IDs. For channel\nmessages, this should contain exactly 1 ID, the ID of the\ntarget channel. For direct messages, this should be an array\nof target user IDs. For unaddressed drafts, this is ignored,\nand clients should send an empty array.\n", + "items": { + "type": "integer" + } + }, + "topic": { + "type": "string", + "description": "For channel message drafts, the tentative topic name. For direct\nor unaddressed messages, this will be ignored and should ideally\nbe the empty string. Should not contain null bytes.\n" + }, + "content": { + "type": "string", + "description": "The body of the draft. Should not contain null bytes.\n" + }, + "timestamp": { + "type": "integer", + "description": "A Unix timestamp (seconds only) representing when the draft was\nlast edited. When creating a draft, this key need not be present\nand it will be filled in automatically by the server.\n", + "example": 1595479019 + } + }, + "additionalProperties": false, + "required": ["type", "to", "topic", "content"] + }, + "NavigationView": { + "type": "object", + "description": "Represents a user's personal configuration for a specific\nnavigation view (displayed most visibly at the top of the web\napplication's left sidebar).\n\nNavigation views can be either an override to the default\nbehavior of a built-in view, or a custom view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", + "additionalProperties": false, + "required": ["fragment", "is_pinned"], + "properties": { + "fragment": { + "type": "string", + "description": "A unique identifier for the view, used to determine navigation\nbehavior when clicked.\n\nClients should use this value to navigate to the corresponding URL hash.\n", + "example": "narrow/is/alerted" + }, + "is_pinned": { + "type": "boolean", + "description": "Determines whether the view appears directly in the sidebar or\nis hidden in the \"More Views\" menu.\n\n- `true` - Pinned and visible in the sidebar.\n- `false` - Hidden and accessible via the \"More Views\" menu.\n", + "example": true + }, + "name": { + "type": "string", + "nullable": true, + "description": "The user-facing name for custom navigation views. Omit this\nfield for built-in views.\n", + "example": "Alert Words" + } + } + }, + "SavedSnippet": { + "type": "object", + "description": "Object containing the details of the saved snippet.\n", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "The unique ID of the saved snippet.\n" + }, + "title": { + "type": "string", + "description": "The title of the saved snippet.\n" + }, + "content": { + "type": "string", + "description": "The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n" + }, + "date_created": { + "type": "integer", + "description": "The UNIX timestamp for when the saved snippet was created, in\nUTC seconds.\n" + } + } + }, + "ScheduledMessageBase": { + "type": "object", + "description": "Object containing details of the scheduled message.\n", + "properties": { + "scheduled_message_id": { + "type": "integer", + "description": "The unique ID of the scheduled message, which can be used to\nmodify or delete the scheduled message.\n\nThis is different from the unique ID that the message will have\nafter it is sent.\n" + }, + "type": { + "type": "string", + "description": "The type of the scheduled message. Either `\"stream\"` or `\"private\"`.\n", + "enum": ["stream", "private"] + }, + "to": { + "oneOf": [ + { + "type": "integer" + }, + { + "type": "array", + "items": { + "type": "integer" + } + } + ], + "description": "The scheduled message's tentative target audience.\n\nFor channel messages, it will be the unique ID of the target\nchannel. For direct messages, it will be an array with the\ntarget users' IDs.\n" + }, + "topic": { + "type": "string", + "description": "Only present if `type` is `\"stream\"`.\n\nThe topic for the channel message.\n" + }, + "content": { + "type": "string", + "description": "The content/body of the scheduled message, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "rendered_content": { + "type": "string", + "description": "The content/body of the scheduled message rendered in HTML.\n" + }, + "scheduled_delivery_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message will be sent\nby the server, in UTC seconds.\n", + "example": 1595479019 + }, + "failed": { + "type": "boolean", + "description": "Whether the server has tried to send the scheduled message\nand it failed to successfully send.\n\nClients that support unscheduling and editing scheduled messages\nshould display scheduled messages with `\"failed\": true` with an\nindicator that the server failed to send the message at the\nscheduled time, so that the user is aware of the failure and can\nget the content of the scheduled message.\n\n**Changes**: New in Zulip 7.0 (feature level 181).\n" + } + }, + "additionalProperties": false, + "required": [ + "scheduled_message_id", + "type", + "to", + "content", + "rendered_content", + "scheduled_delivery_timestamp", + "failed" + ] + }, + "ScheduledMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ScheduledMessageBase" + }, + { + "additionalProperties": false, + "properties": { + "scheduled_message_id": {}, + "type": {}, + "to": {}, + "topic": {}, + "content": {}, + "rendered_content": {}, + "scheduled_delivery_timestamp": {}, + "failed": {} + } + } + ] + }, + "Reminder": { + "type": "object", + "additionalProperties": false, + "description": "Object containing details of the scheduled message.\n", + "properties": { + "reminder_id": { + "type": "integer", + "description": "The unique ID of the reminder, which can be used to\ndelete the reminder.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n" + }, + "type": { + "type": "string", + "description": "The type of the reminder. Always set to `\"private\"`.\n", + "enum": ["private"] + }, + "to": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "Contains the ID of the user who scheduled the reminder,\nand to which the reminder will be sent.\n" + }, + "content": { + "type": "string", + "description": "The content/body of the reminder, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + }, + "rendered_content": { + "type": "string", + "description": "The content/body of the reminder rendered in HTML.\n" + }, + "scheduled_delivery_timestamp": { + "type": "integer", + "description": "The UNIX timestamp for when the message will be sent\nby the server, in UTC seconds.\n", + "example": 1595479019 + }, + "failed": { + "type": "boolean", + "description": "Whether the server has tried to send the reminder\nand it failed to successfully send.\n\nClients that support unscheduling reminders\nshould display scheduled messages with `\"failed\": true` with an\nindicator that the server failed to send the message at the\nscheduled time, so that the user is aware of the failure and can\nget the content of the scheduled message.\n" + }, + "reminder_target_message_id": { + "type": "integer", + "description": "The ID of the message that the reminder is created for.\n" + } + }, + "required": [ + "reminder_id", + "type", + "to", + "content", + "rendered_content", + "scheduled_delivery_timestamp", + "failed", + "reminder_target_message_id" + ] + }, + "GroupPermissionSetting": { + "description": "Configuration for a group permission setting specifying the groups\nto which the setting can be set to and the default values for the\nsetting.\n\n**Changes**: Removed `allow_owners_group` field in Zulip 10.0 (feature level 326), as we now\nsupport anonymous user groups. Previously, the `role:owners` system group was\nnot offered when `allow_owners_group` was false.\n\nRemoved unnecessary `id_field_name` field in Zulip 10.0 (feature level 326). Previously,\nthis always had the value of `\"{setting_name}_id\"`; it was an internal implementation\ndetail of the server not intended to be included in the API.\n", + "additionalProperties": false, + "type": "object", + "properties": { + "require_system_group": { + "type": "boolean", + "description": "Whether the setting can only be set to a system user group.\n" + }, + "allow_internet_group": { + "type": "boolean", + "description": "Whether the setting can be set to `role:internet` system group.\n" + }, + "allow_nobody_group": { + "type": "boolean", + "description": "Whether the setting can be set to `role:nobody` system group.\n" + }, + "allow_everyone_group": { + "type": "boolean", + "description": "Whether the setting can be set to `role:everyone` system group.\n\nIf false, guest users cannot exercise this permission even if they are part of\nthe [group-setting value](/api/group-setting-values) for this setting.\n" + }, + "default_group_name": { + "type": "string", + "description": "Name of the default group for the setting.\n" + }, + "default_for_system_groups": { + "type": "string", + "nullable": true, + "description": "Name of the default group for the setting for system groups.\n\nThis is non-null only for group-level settings.\n" + }, + "allowed_system_groups": { + "type": "array", + "description": "An array of names of system groups to which the setting can\nbe set to.\n\nIf the list is empty, the setting can be set to system groups\nbased on the other boolean fields.\n\n**Changes**: New in Zulip 8.0 (feature level 225).\n", + "items": { + "type": "string" + } + } + } + }, + "User": { + "allOf": [ + { + "$ref": "#/components/schemas/UserBase" + }, + { + "additionalProperties": false, + "properties": { + "user_id": {}, + "delivery_email": { + "nullable": true + }, + "email": {}, + "full_name": {}, + "date_joined": {}, + "is_active": {}, + "is_owner": {}, + "is_admin": {}, + "is_guest": {}, + "is_bot": {}, + "bot_type": { + "nullable": true + }, + "bot_owner_id": { + "nullable": true + }, + "role": {}, + "timezone": {}, + "avatar_url": { + "nullable": true + }, + "avatar_version": {}, + "profile_data": {} + } + } + ] + }, + "UserBase": { + "type": "object", + "description": "A dictionary containing basic data on a given Zulip user.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was\nreplaced by the `can_manage_billing_group` realm setting.\n", + "properties": { + "user_id": { + "type": "integer", + "description": "The unique ID of the user.\n" + }, + "delivery_email": { + "type": "string", + "nullable": true, + "description": "The user's real email address. This value will be `null` if you cannot\naccess user's real email address. For bot users, this field is always\nset to the real email of the bot, because bot users always have\n`email_address_visibility` set to everyone.\n\n**Changes**: Prior to Zulip 7.0 (feature level 163), this field was\npresent only when `email_address_visibility` was restricted and you had\naccess to the user's real email. As of this feature level, this field\nis always present, including the case when `email_address_visibility`\nis set to everyone (and therefore not restricted).\n" + }, + "email": { + "type": "string", + "description": "The Zulip API email address of the user or bot.\n\nIf you do not have permission to view the email address of the target user,\nthis will be a fake email address that is usable for the Zulip API but nothing else.\n" + }, + "full_name": { + "type": "string", + "description": "Full name of the user or bot, used for all display purposes.\n" + }, + "date_joined": { + "type": "string", + "description": "The time the user account was created.\n" + }, + "is_active": { + "type": "boolean", + "description": "A boolean specifying whether the user account has been deactivated.\n" + }, + "is_owner": { + "type": "boolean", + "description": "A boolean specifying whether the user is an organization owner.\nIf true, `is_admin` will also be true.\n\n**Changes**: New in Zulip 3.0 (feature level 8).\n" + }, + "is_admin": { + "type": "boolean", + "description": "A boolean specifying whether the user is an organization administrator.\n" + }, + "is_guest": { + "type": "boolean", + "description": "A boolean specifying whether the user is a guest user.\n" + }, + "is_bot": { + "type": "boolean", + "description": "A boolean specifying whether the user is a bot or full account.\n" + }, + "bot_type": { + "type": "integer", + "nullable": true, + "description": "An integer describing the type of bot:\n\n- `null` if the user isn't a bot.\n- `1` for a `Generic` bot.\n- `2` for an `Incoming webhook` bot.\n- `3` for an `Outgoing webhook` bot.\n- `4` for an `Embedded` bot.\n" + }, + "bot_owner_id": { + "type": "integer", + "nullable": true, + "description": "If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`\nis the user ID of the bot's owner (usually, whoever created the bot).\n\nWill be `null` for legacy bots that do not have an owner.\n\n**Changes**: New in Zulip 3.0 (feature level 1). In previous\nversions, there was a `bot_owner` field containing the email\naddress of the bot's owner.\n" + }, + "role": { + "type": "integer", + "enum": [100, 200, 300, 400, 600], + "description": "[Organization-level role](/api/roles-and-permissions) of the user.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" + }, + "timezone": { + "type": "string", + "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n" + }, + "avatar_url": { + "type": "string", + "nullable": true, + "description": "URL for the user's avatar.\n\nWill be `null` if the `client_gravatar`\nquery parameter was set to `true`, the current user has access to\nthis user's real email address, and this user's avatar is hosted by\nthe Gravatar provider (i.e. this user has never uploaded an avatar).\n\n**Changes**: Before Zulip 7.0 (feature level 163), access to a\nuser's real email address was a realm-level setting. As of this\nfeature level, `email_address_visibility` is a user setting.\n\nIn Zulip 3.0 (feature level 18), if the client has the\n`user_avatar_url_field_optional` capability, this will be missing at\nthe server's sole discretion.\n" + }, + "avatar_version": { + "type": "integer", + "description": "Version for the user's avatar. Used for cache-busting requests\nfor the user's avatar. Clients generally shouldn't need to use this;\nmost avatar URLs sent by Zulip will already end with `?v={avatar_version}`.\n" + }, + "profile_data": { + "$ref": "#/components/schemas/profile_data" + } + } + }, + "profile_data": { + "type": "object", + "description": "Only present if `is_bot` is false; bots can't have custom profile fields.\n\nA dictionary containing custom profile field data for the user. Each entry\nmaps the integer ID of a custom profile field in the organization to a\ndictionary containing the user's data for that field. Generally the data\nincludes just a single `value` key; for those custom profile fields\nsupporting Markdown, a `rendered_value` key will also be present.\n", + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "description": "`{id}`: Object with data about what value the user filled in the custom\nprofile field with that ID.\n", + "properties": { + "value": { + "type": "string", + "description": "User's personal value for this custom profile field.\n" + }, + "rendered_value": { + "type": "string", + "description": "The `value` rendered in HTML. Will only be present for\ncustom profile field types that support Markdown rendering.\n\nThis user-generated HTML content should be rendered\nusing the same CSS and client-side security protections\nas are used for message content.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" + } + } + } + }, + "ChannelFolder": { + "type": "object", + "additionalProperties": false, + "description": "Object containing the channel folder's attributes.\n", + "properties": { + "id": { + "type": "integer", + "description": "The unique ID of the channel folder.\n" + }, + "name": { + "type": "string", + "description": "The name of the channel folder.\n" + }, + "order": { + "type": "integer", + "description": "This value determines in which order the channel folder should be\ndisplayed in the UI. The value is 0 indexed, and a channel folder with\na lower value should be displayed before channel folders with higher\nvalues.\n\n**Changes**: New in Zulip 11.0 (feature level 414).\n" + }, + "date_created": { + "type": "integer", + "nullable": true, + "description": "The UNIX timestamp for when the channel folder was created,\nin UTC seconds.\n" + }, + "creator_id": { + "type": "integer", + "nullable": true, + "description": "The ID of the user who created the channel folder.\n" + }, + "description": { + "type": "string", + "description": "The description of the channel folder. Can be an empty string.\n\nSee [Markdown message formatting](/api/message-formatting) for details\non Zulip's HTML format.\n" + }, + "rendered_description": { + "type": "string", + "description": "The description of the channel folder rendered as HTML, intended to be\nused for UI that displays the channel folder description.\n\nClients should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax work\ncorrectly. And any client-side security logic for user-generated\nmessage content should be applied when displaying this HTML as though\nit were the body of a Zulip message.\n" + }, + "is_archived": { + "type": "boolean", + "description": "Whether the channel folder is archived or not.\n" + } + } + }, + "JsonResponseBase": { + "type": "object", + "properties": { + "result": { + "type": "string" + } + } + }, + "JsonSuccess": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {} + }, + "example": { + "msg": "", + "result": "success" + } + } + ] + }, + "JsonSuccessBase": { + "description": "**Changes**: As of Zulip 7.0 (feature level 167), if any\nparameters sent in the request are not supported by this\nendpoint, a successful JSON response will include an\n[`ignored_parameters_unsupported`][ignored_params] array.\n\nA typical successful JSON response may look like:\n\n[ignored_params]: /api/rest-error-handling#ignored-parameters\n", + "allOf": [ + { + "$ref": "#/components/schemas/JsonResponseBase" + }, + { + "required": ["result", "msg"], + "properties": { + "result": { + "enum": ["success"] + }, + "msg": { + "type": "string" + }, + "ignored_parameters_unsupported": { + "$ref": "#/components/schemas/IgnoredParametersUnsupported" + } + } + } + ] + }, + "IgnoredParametersSuccess": { + "allOf": [ + { + "$ref": "#/components/schemas/IgnoredParametersBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {} + } + } + ], + "description": "**Changes**: The [`ignored_parameters_unsupported`][ignored_params]\narray was added as a possible return value for all REST API endpoint\nJSON success responses in Zulip 7.0 (feature level 167).\n\nPreviously, it was added to\n[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings)\nin Zulip 5.0 (feature level 111) and to\n[`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults)\nin Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0\n(feature level 78) as a return value for the\n[`PATCH /settings`](/api/update-settings) endpoint.\n\nA typical successful JSON response with ignored parameters may look like:\n\n[ignored_params]: /api/rest-error-handling#ignored-parameters\n", + "example": { + "ignored_parameters_unsupported": [ + "invalid_param_1", + "invalid_param_2" + ], + "msg": "", + "result": "success" + } + }, + "IgnoredParametersBase": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonResponseBase" + }, + { + "required": ["result", "msg"], + "properties": { + "result": { + "enum": ["success"] + }, + "msg": { + "type": "string" + }, + "ignored_parameters_unsupported": { + "$ref": "#/components/schemas/IgnoredParametersUnsupported" + } + } + } + ] + }, + "ApiKeyResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonSuccessBase" + }, + { + "required": ["api_key", "email"], + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "ignored_parameters_unsupported": {}, + "api_key": { + "type": "string", + "description": "The API key that can be used to authenticate as the requested user.\n" + }, + "email": { + "type": "string", + "description": "The email address of the user who owns the API key.\n" + }, + "user_id": { + "type": "integer", + "description": "The unique ID of the user who owns the API key.\n\n**Changes**: New in Zulip 7.0 (feature level 171).\n" + } + }, + "example": { + "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv", + "email": "iago@zulip.com", + "msg": "", + "result": "success", + "user_id": 5 + } + } + ] + }, + "CodedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {} + } + } + ] + }, + "CodedErrorBase": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonResponseBase" + }, + { + "required": ["result", "msg", "code"], + "properties": { + "result": { + "enum": ["error"] + }, + "msg": { + "type": "string" + }, + "code": { + "type": "string", + "description": "A string that identifies the error.\n" + } + } + } + ] + }, + "BadEventQueueIdError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "queue_id": { + "type": "string", + "description": "The string that identifies the invalid event queue.\n" + } + }, + "example": { + "code": "BAD_EVENT_QUEUE_ID", + "msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8", + "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", + "result": "error" + } + } + ] + }, + "InvalidMessageError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {} + }, + "example": { + "msg": "Invalid message(s)", + "code": "BAD_REQUEST", + "result": "error" + } + } + ] + }, + "InvalidChannelError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {} + }, + "example": { + "msg": "Invalid channel ID", + "code": "BAD_REQUEST", + "result": "error" + } + } + ] + }, + "NonExistingChannelNameError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "stream": { + "type": "string", + "description": "The name of the channel that could not be found.\n" + } + }, + "example": { + "code": "STREAM_DOES_NOT_EXIST", + "msg": "Channel 'nonexistent' does not exist", + "result": "error", + "stream": "nonexistent" + } + } + ] + }, + "NonExistingChannelIdError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "stream_id": { + "type": "integer", + "description": "The channel ID that could not be found.\n" + } + }, + "example": { + "code": "STREAM_DOES_NOT_EXIST", + "msg": "Channel with ID '9' does not exist", + "result": "error", + "stream_id": 9 + } + } + ] + }, + "InvalidApiKeyError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "INVALID_API_KEY", + "msg": "Invalid API key", + "result": "error" + }, + "description": "### Invalid API key\n\nA typical failed JSON response for when the API key is invalid.\n" + } + ] + }, + "InvitationFailedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "errors": { + "type": "array", + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "boolean" + } + ] + } + }, + "description": "An array of arrays of length 3, where each inner array consists of (a) an email\naddress that was skipped while sending invitations, (b) the corresponding error\nmessage, and (c) a boolean which is `true` when the email address already uses Zulip\nand the corresponding user is deactivated in the organization.\n" + }, + "sent_invitations": { + "description": "A boolean specifying whether any invitations were sent.\n", + "type": "boolean" + }, + "daily_limit_reached": { + "type": "boolean", + "description": "A boolean specifying whether the limit on the number of invitations that can\nbe sent in the organization in a day has been reached.\n" + }, + "license_limit_reached": { + "type": "boolean", + "description": "A boolean specifying whether the organization have enough unused Zulip licenses\nto invite specified number of users.\n" + } + } + } + ] + }, + "MissingArgumentError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "description": "### Missing request parameter\n\nA typical failed JSON response for when a required request parameter\nis not supplied.\n\nThe value of `var_name` contains information about the missing parameter.\n", + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "var_name": { + "type": "string", + "description": "It contains the information about the missing parameter.\n" + } + }, + "example": { + "code": "REQUEST_VARIABLE_MISSING", + "msg": "Missing 'content' argument", + "result": "error", + "var_name": "content" + } + } + ] + }, + "IncompatibleParametersError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "description": "### Incompatible request parameters\n\nA typical failed JSON response for when two or more, optional\nparameters are supplied that are incompatible with each other.\n\nThe value of `parameters` in the response is string containing\nthe parameters, separated by commas, that are incompatible.\n", + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "parameters": { + "type": "string", + "description": "A string containing the parameters, separated by commas,\nthat are incompatible.\n" + } + }, + "example": { + "code": "BAD_REQUEST", + "msg": "Unsupported parameter combination: object_id, object_name", + "result": "error", + "parameters": "object_id, object_name" + } + } + ] + }, + "UserNotAuthorizedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "BAD_REQUEST", + "msg": "User not authorized for this query", + "result": "error" + }, + "description": "### User not authorized for query\n\nA typical failed JSON response for when the user is not authorized for\na query.\n" + } + ] + }, + "UserDeactivatedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "USER_DEACTIVATED", + "msg": "Account is deactivated", + "result": "error" + }, + "description": "### User account deactivated\n\nA typical failed json response for when user's account is deactivated.\n\n**Changes**: As of Zulip 5.0 (feature level 76), these errors use the\nHTTP 401 status code. Before this feature level, they used the HTTP 403\nstatus code.\n" + } + ] + }, + "RateLimitedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedErrorBase" + }, + { + "additionalProperties": false, + "description": "### Rate limit exceeded\n\nA typical failed JSON response for when a rate limit is exceeded.\nZulip sets a few [HTTP response headers][rate-limit-headers]\nto help with preventing rate limit errors.\n\nThe value of `retry-after` in the response indicates how many\nseconds the client must wait before making additional requests.\n\n**Changes**: Before Zulip 4.0 (feature level 36), the `code` key\nwas not present in rate limit errors.\n\n[rate-limit-headers]: /api/http-headers#rate-limiting-response-headers\n", + "properties": { + "result": {}, + "msg": {}, + "code": {}, + "retry-after": { + "type": "integer", + "description": "How many seconds the client must wait before making\nadditional requests.\n" + } + }, + "example": { + "code": "RATE_LIMIT_HIT", + "msg": "API usage exceeded rate limit", + "result": "error", + "retry-after": 28.706807374954224 + } + } + ] + }, + "RealmDeactivatedError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "REALM_DEACTIVATED", + "msg": "This organization is deactivated", + "result": "error" + }, + "description": "### Realm deactivated\n\nA typical failed json response for when user's organization is deactivated.\n\n**Changes**: As of Zulip 5.0 (feature level 76), these errors use the\nHTTP 401 status code. Before this feature level, they used the HTTP 403\nstatus code.\n" + } + ] + }, + "InvalidPushDeviceTokenError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "INVALID_PUSH_DEVICE_TOKEN", + "msg": "Device not recognized", + "result": "error" + }, + "description": "## Invalid push device token\n\nA typical failed JSON response for when the push device token is not\nrecognized by the Zulip server:\n" + } + ] + }, + "InvalidRemotePushDeviceTokenError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "INVALID_REMOTE_PUSH_DEVICE_TOKEN", + "msg": "Device not recognized by the push bouncer", + "result": "error" + }, + "description": "## Invalid push device token\n\nA typical failed JSON response for when the push device token is not recognized\nby the push notification bouncer:\n" + } + ] + }, + "NoActivePushDeviceError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "NO_ACTIVE_PUSH_DEVICE", + "msg": "No active registered push device", + "result": "error" + }, + "description": "## No active push device\n\nA typical failed JSON response for when no registered device is available\nfor the user (and `push_account_id`) to receive a push notification.\n" + } + ] + }, + "FailedToConnectBouncerError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "FAILED_TO_CONNECT_BOUNCER", + "msg": "Network error while connecting to Zulip push notification service.", + "result": "error" + }, + "description": "## Failed to connect bouncer\n\nA typical failed JSON response for when a network error occurs\nwhile the server attempts to connect to the bouncer server.\n" + } + ] + }, + "InternalBouncerServerError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "INTERNAL_SERVER_ERROR_ON_BOUNCER", + "msg": "Internal server error on Zulip push notification service, retry later.", + "result": "error" + }, + "description": "## Internal bouncer server error\n\nA typical failed JSON response for when a 5xx error occurs on the bouncer server.\n" + } + ] + }, + "PushNotificationAdminActionRequiredError": { + "allOf": [ + { + "$ref": "#/components/schemas/CodedError" + }, + { + "example": { + "code": "ADMIN_ACTION_REQUIRED", + "msg": "Push notification configuration issue on server, contact the server administrator or retry later.", + "result": "error" + }, + "description": "## Admin action required\n\nA typical failed JSON response for when there is a push notification\nconfiguration issue on the server, such as invalid credentials,\nan expired plan, or an unregistered organization. Admin action is required.\n" + } + ] + }, + "Event_types": { + "description": "A JSON-encoded array indicating which types of events you're interested\nin. Values that you might find useful include:\n\n- **message** (messages)\n- **subscription** (changes in your subscriptions)\n- **realm_user** (changes to users in the organization and\n their properties, such as their name).\n\nIf you do not specify this parameter, you will receive all\nevents, and have to filter out the events not relevant to\nyour client in your client code. For most applications, one\nis only interested in messages, so one specifies:\n`\"event_types\": [\"message\"]`\n\nEvent types not supported by the server are ignored, in order to simplify\nthe implementation of client apps that support multiple server versions.\n", + "type": "array", + "items": { + "type": "string" + }, + "example": ["message"] + }, + "Narrow": { + "description": "A JSON-encoded array of arrays of length 2 indicating the\n[narrow filter(s)](/api/construct-narrow) for which you'd\nlike to receive events for.\n\nFor example, to receive events for direct messages (including\ngroup direct messages) received by the user, one can use\n`\"narrow\": [[\"is\", \"dm\"]]`.\n\nUnlike the API for [fetching messages](/api/get-messages),\nthis narrow parameter is simply a filter on messages that the\nuser receives through their channel subscriptions (or because\nthey are a recipient of a direct message).\n\nThis means that a client that requests a `narrow` filter of\n`[[\"channel\", \"Denmark\"]]` will receive events for new messages\nsent to that channel while the user is subscribed to that\nchannel. The client will not receive any message events at all\nif the user is not subscribed to `\"Denmark\"`.\n\nNewly created bot users are not usually subscribed to any\nchannels, so bots using this API need to be\n[subscribed](/api/subscribe) to any channels whose messages\nyou'd like them to process using this endpoint.\n\nSee the `all_public_streams` parameter for how to process all\npublic channel messages in an organization.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string" + } + }, + "default": [], + "example": [["channel", "Denmark"]] + }, + "AllPublicChannels": { + "description": "Whether you would like to request message events from all public\nchannels. Useful for workflow bots that you'd like to see all new messages\nsent to public channels. (You can also subscribe the user to private channels).\n", + "type": "boolean", + "default": false, + "example": true + }, + "RequiredContent": { + "description": "The content of the message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n", + "type": "string", + "example": "Hello" + }, + "OptionalContent": { + "description": "The updated content of the target message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n\nNote that a message's content and channel cannot be changed at the\nsame time, so sending both `content` and `stream_id` parameters will\nthrow an error.\n", + "type": "string", + "example": "Hello" + }, + "HistoryPublicToSubscribers": { + "description": "Whether the channel's message history should be available to\nnewly subscribed members, or users can only access messages\nthey actually received while subscribed to the channel.\n\nCorresponds to the shared history option for\n[private channels](/help/channel-permissions#private-channels).\n", + "type": "boolean", + "example": false + }, + "Principals": { + "description": "A list of user IDs (preferred) or Zulip API email\naddresses of the users to be subscribed to or unsubscribed\nfrom the channels specified in the `subscriptions` parameter. If\nnot provided, then the requesting user/bot is subscribed.\n\n**Changes**: The integer format is new in Zulip 3.0 (feature level 9).\n", + "oneOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "array", + "items": { + "type": "integer" + } + } + ], + "example": ["ZOE@zulip.com"] + }, + "ReactionType": { + "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nIf an API client is adding/removing a vote on an existing reaction,\nit should pass this parameter using the value the server provided\nfor the existing reaction for specificity. Supported values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: In Zulip 3.0 (feature level 2), this parameter became\noptional for [custom emoji](/help/custom-emoji);\npreviously, this endpoint assumed `unicode_emoji` if this\nparameter was not specified.\n", + "type": "string", + "example": "unicode_emoji" + }, + "EmojiCode": { + "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\nFor most API clients, you won't need this, but it's important\nfor Zulip apps to handle rare corner cases when\nadding/removing votes on an emoji reaction added previously by\nanother user.\n\nIf the existing reaction was added when the Zulip server was\nusing a previous version of the emoji data mapping between\nUnicode codepoints and human-readable names, sending the\n`emoji_code` in the data for the original reaction allows the\nZulip server to correctly interpret your upvote as an upvote\nrather than a reaction with a \"different\" emoji.\n", + "type": "string", + "example": "1f419" + }, + "MessageRetentionDays": { + "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). Two special string format\nvalues are supported:\n\n- `\"realm_default\"`: Return to the organization-level setting.\n- `\"unlimited\"`: Retain messages forever.\n\n**Changes**: Prior to Zulip 5.0 (feature level 91), retaining\nmessages forever was encoded using `\"forever\"` instead of\n`\"unlimited\"`.\n\nNew in Zulip 3.0 (feature level 17).\n", + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer" + } + ], + "example": "20" + }, + "TopicsPolicy": { + "type": "string", + "enum": [ + "inherit", + "allow_empty_topic", + "disable_empty_topic", + "empty_topic_only" + ], + "example": "inherit", + "description": "Whether [named topics](/help/introduction-to-topics) and the empty\ntopic (i.e., [\"general chat\" topic](/help/general-chat-topic))\nare enabled in this channel.\n\n- `\"inherit\"`: Messages can be sent to named topics in this channel,\n and the [organization-level `realm_topics_policy`][realm-topics-policy]\n is used for whether messages can be sent to the empty topic in this\n channel.\n- `\"allow_empty_topic\"`: Messages can be sent to both named topics and\n the empty topic in this channel.\n- `\"disable_empty_topic\"`: Messages can be sent to named topics in this\n channel, but the empty topic is disabled.\n- `\"empty_topic_only\"`: Messages can be sent to the empty topic in this\n channel, but named topics are disabled. See [\"general chat\"\n channels](/help/general-chat-channels).\n\nThe `\"empty_topic_only\"` policy can only be set if all existing messages\nin the channel are already in the empty topic.\n\nWhen creating a new channel, if the `topics_policy` is not specified, the\n`\"inherit\"` option will be set.\n\n**Changes**: In Zulip 11.0 (feature level 404), the `\"empty_topic_only\"`\noption was added.\n\nNew in Zulip 11.0 (feature level 392).\n\n[realm-topics-policy]: /help/require-topics#set-the-default-general-chat-topic-configuration\n" + }, + "SendNewSubscriptionMessages": { + "description": "Whether any other users newly subscribed via this request should be\nsent a direct message, from Notification Bot, notifying them about their\nnew subscription.\n\nNo direct messages are sent for any channels that are created as part of\nthis request, regardless of the value of this parameter.\n\nThe server will never send direct messages when the total number of users\nwho were subscribed to channels in this request was more than the value\nof `max_bulk_new_subscription_messages`, which is available in the [`POST\n/register`](/api/register-queue) response.\n\n**Changes**: Before Zulip 11.0 (feature level 397), new subscribers\nwere always sent a Notification Bot direct message, which was unduly\nexpensive when bulk-subscribing thousands of users to a channel.\n", + "type": "boolean", + "default": true, + "example": true + }, + "ChannelCanAddSubscribersGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to add subscribers to this channel.\n\nUsers who can administer the channel or have similar realm-level\npermissions can add subscribers to a public channel regardless\nof the value of this setting.\n\nUsers in this group need not be subscribed to a private channel to\nadd subscribers to it.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 342). Previously, there was no\nchannel-level setting for this permission.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanRemoveSubscribersGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to remove subscribers from this channel.\n\nOrganization administrators can unsubscribe others from a channel as though\nthey were in this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), channel administrators\ncould not unsubscribe other users if they were not an organization\nadministrator or part of `can_remove_subscribers_group`. Realm administrators\nwere not allowed to unsubscribe other users from a private channel if they\nwere not subscribed to that channel.\n\nPrior to Zulip 10.0 (feature level 320), this value was always the integer\nID of a system group.\n\nBefore Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`\nsetting was named `can_remove_subscribers_group_id`.\n\nNew in Zulip 6.0 (feature level 142).\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanAdministerChannelGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to administer this channel.\n\nOrganization administrators can administer every channel as though they were\nin this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349) a user needed to\n[have content access](/help/channel-permissions) to a channel in\norder to modify it. The exception to this rule was that organization\nadministrators can edit channel names and descriptions without\nhaving full access to the channel.\n\nNew in Zulip 10.0 (feature level 325). Prior to this\nchange, the permission to administer channels was limited to realm\nadministrators.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanDeleteAnyMessageGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to delete any message in the channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete any message in the channel.\n\nUsers present in the organization-level `can_delete_any_message_group`\nsetting can always delete any message in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in `can_delete_any_message_group` were able\ndelete any message in the organization.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanDeleteOwnMessageGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to delete the messages that they have sent in the channel.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete their own message in the channel.\n\nUsers with permission to delete any message in the channel\nand users present in the organization-level `can_delete_own_message_group` setting\ncan always delete their own messages in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in the organization-level `can_delete_any_message_group`\nand `can_delete_own_message_group` settings were able delete their own messages in\nthe organization.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanMoveMessagesOutOfChannelGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to move messages out of this channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages out of the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_channels_group` setting can always move messages\nout of the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_channels_group` were able\nmove messages between channels.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanMoveMessagesWithinChannelGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to move messages within this channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages within the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_topics_group` setting can always move messages\nwithin the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_topics_group` were able\nmove messages between topics of a channel.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanSendMessageGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to post in this channel.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 333). Previously\n`stream_post_policy` field used to control the permission to\npost in the channel.\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanSubscribeGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to subscribe themselves to this channel.\n\nEveryone, excluding guests, can subscribe to any public channel\nirrespective of this setting.\n\nUsers in this group can subscribe to a private channel as well.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 357).\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "CanResolveTopicsGroup": { + "allOf": [ + { + "$ref": "#/components/schemas/GroupSettingValue" + }, + { + "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to resolve topics in the channel.\n\nUsers who have similar realm-level permissions can resolve topics\nin a channel regardless of the value of this setting.\n\n**Changes**: New in Zulip 11.0 (feature level 402).\n\n[setting-values]: /api/group-setting-values\n" + } + ] + }, + "LinkifierPattern": { + "description": "The [Python regular\nexpression](https://docs.python.org/3/howto/regex.html) that should\ntrigger the linkifier.\n", + "type": "string", + "example": "#(?P[0-9]+)" + }, + "LinkifierURLTemplate": { + "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template used for the link.\nIf you used named groups in `pattern`, you can insert their\ncontent here with `{name_of_group}`.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced\nthe `url_format_string` parameter, which was a format string in which\nnamed groups' content could be inserted with `%(name_of_group)s`.\n", + "type": "string", + "example": "https://github.com/zulip/zulip/issues/{id}" + }, + "FolderId": { + "type": "integer", + "nullable": true, + "description": "The ID of the folder to which the channel belongs.\n\nIs `null` if channel does not belong to any folder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" + } + }, + "responses": { + "SimpleSuccess": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/JsonSuccess" + } + } + } + }, + "SuccessIgnoredParameters": { + "description": "Success.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/IgnoredParametersSuccess" + } + ] + } + } + } + } + }, + "requestBodies": { + "UpdateUser": { + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "full_name": { + "description": "The user's full name.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 5.0 (feature level 106).\n", + "type": "string", + "example": "NewName" + }, + "role": { + "description": "New [role](/api/roles-and-permissions) for the user. Roles are encoded as:\n\n- Organization owner: 100\n- Organization administrator: 200\n- Organization moderator: 300\n- Member: 400\n- Guest: 600\n\nOnly organization owners can add or remove the owner role.\n\nThe owner role cannot be removed from the only organization owner.\n\n**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous\npair of `is_admin` and `is_guest` boolean parameters. Organization moderator\nrole added in Zulip 4.0 (feature level 60).\n", + "type": "integer", + "example": 400 + }, + "profile_data": { + "description": "A dictionary containing the updated custom profile field data for the user.\n", + "type": "array", + "items": { + "type": "object" + }, + "example": [ + { + "id": 4, + "value": "0" + }, + { + "id": 5, + "value": "1909-04-05" + } + ] + }, + "new_email": { + "description": "New email address for the user. Requires the user making the request\nto be an organization owner and additionally have the `.can_change_user_emails`\nspecial permission.\n\n**Changes**: New in Zulip 10.0 (feature level 285).\n", + "type": "string", + "example": "username@example.com" + } + } + }, + "encoding": { + "role": { + "contentType": "application/json" + }, + "profile_data": { + "contentType": "application/json" + } + } + } + } + } + }, + "parameters": { + "UserGroupId": { + "name": "user_group_id", + "in": "path", + "description": "The ID of the target user group.\n", + "schema": { + "type": "integer" + }, + "example": 38, + "required": true + }, + "QueueId": { + "name": "queue_id", + "in": "query", + "description": "The ID of an event queue that was previously registered via\n`POST /api/v1/register` (see [Register a queue](/api/register-queue)).\n", + "schema": { + "type": "string" + }, + "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8", + "required": true + }, + "ChannelIdInPath": { + "name": "stream_id", + "in": "path", + "description": "The ID of the channel to access.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + }, + "ClientGravatar": { + "name": "client_gravatar", + "in": "query", + "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n", + "schema": { + "type": "boolean", + "default": true + }, + "example": false + }, + "MessageId": { + "name": "message_id", + "in": "path", + "description": "The target message's ID.\n", + "schema": { + "type": "integer" + }, + "example": 43, + "required": true + }, + "UserId": { + "name": "user_id", + "in": "path", + "description": "The target user's ID.\n", + "schema": { + "type": "integer" + }, + "example": 12, + "required": true + }, + "MutedUserId": { + "name": "muted_user_id", + "in": "path", + "description": "The ID of the user to mute/unmute.\n\n**Changes**: Before Zulip 8.0 (feature level 188), bot users could not\nbe muted/unmuted, and specifying a bot user's ID returned an error response.\n", + "schema": { + "type": "integer" + }, + "example": 10, + "required": true + }, + "IncludeSubscribers": { + "name": "include_subscribers", + "in": "query", + "description": "Whether each returned channel object should include a `subscribers`\nfield containing a list of the user IDs of its subscribers.\n\nClient apps supporting organizations with many thousands of users\nshould not pass `true`, because the full subscriber matrix may be\nseveral megabytes of data. The `partial` value, combined with the\n`subscriber_count` and fetching subscribers for individual channels as\nneeded, is recommended to support client app features where\nchannel subscriber data is useful.\n\nIf a client passes `partial` for this parameter, the server may,\nfor some channels, return a subset of the channel's subscribers\nin the `partial_subscribers` field instead of the `subscribers` field,\nwhich always contains the complete set of subscribers.\n\nThe server guarantees that it will always return a `subscribers`\nfield for channels with fewer than 250 total subscribers. When\nreturning a `partial_subscribers` field, the server guarantees\nthat all bot users and users active within the last 14 days will\nbe included. For other cases, the server may use its discretion\nto determine which channels and users to include, balancing between\npayload size and usefulness of the data provided to the client.\n\n**Changes**: The `partial` value is new in Zulip 11.0 (feature level 412).\n\nNew in Zulip 2.1.0.\n", + "schema": { + "type": "string", + "enum": ["true", "false", "partial"], + "default": "false" + }, + "example": "true" + }, + "IncludeCustomProfileFields": { + "name": "include_custom_profile_fields", + "in": "query", + "description": "Whether the client wants [custom profile field](/help/custom-profile-fields)\ndata to be included in the response.\n\n**Changes**: New in Zulip 2.1.0. Previous versions do not offer these\ndata via the API.\n", + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + "DirectMemberOnly": { + "name": "direct_member_only", + "in": "query", + "description": "Whether to consider only the direct members of user group and not members\nof its subgroups. Default is `false`.\n", + "schema": { + "type": "boolean" + }, + "example": false, + "required": false + }, + "ChannelFolderId": { + "name": "channel_folder_id", + "in": "path", + "description": "The ID of the target channel folder.\n", + "schema": { + "type": "integer" + }, + "example": 1, + "required": true + } + } + } +} diff --git a/forms-bridge/addons/zulip/hooks.php b/forms-bridge/addons/zulip/hooks.php new file mode 100644 index 00000000..26a242e9 --- /dev/null +++ b/forms-bridge/addons/zulip/hooks.php @@ -0,0 +1,99 @@ + array( + array( + 'ref' => '#backend', + 'name' => 'name', + 'description' => __( + 'Label of the Zulip API backend connection', + 'forms-bridge' + ), + 'default' => 'Zulip API', + ), + array( + 'ref' => '#backend', + 'name' => 'base_url', + 'description' => __( + 'Base URL of your Zulip', + 'forms-bridge' + ), + 'type' => 'url', + 'default' => 'https://your-organization.zulipchat.com', + ), + array( + 'ref' => '#credential', + 'name' => 'name', + 'label' => __( 'Name', 'forms-bridge' ), + 'type' => 'text', + 'required' => true, + ), + array( + 'ref' => '#credential', + 'name' => 'schema', + 'type' => 'text', + 'value' => 'Basic', + ), + array( + 'ref' => '#credential', + 'name' => 'client_id', + 'label' => __( 'User email', 'forms-bridge' ), + 'type' => 'text', + ), + array( + 'ref' => '#credential', + 'name' => 'client_secret', + 'label' => __( 'API key', 'forms-bridge' ), + 'description' => __( + 'You can get it from the "Account & privacy" section of your profile menu', + 'forms-bridge' + ), + 'type' => 'text', + 'required' => true, + ), + array( + 'ref' => '#bridge', + 'name' => 'method', + 'value' => 'POST', + ), + ), + 'bridge' => array( + 'backend' => '', + 'endpoint' => '', + 'method' => 'POST', + ), + 'backend' => array( + 'name' => 'Zulip API', + ), + 'credential' => array( + 'name' => '', + 'schema' => 'Basic', + 'client_id' => '', + 'client_secret' => '', + ), + ), + $defaults, + $schema + ); + }, + 10, + 3 +); diff --git a/forms-bridge/addons/zulip/templates/support.php b/forms-bridge/addons/zulip/templates/support.php new file mode 100644 index 00000000..b3b709ea --- /dev/null +++ b/forms-bridge/addons/zulip/templates/support.php @@ -0,0 +1,128 @@ + __( 'Support Stream', 'forms-bridge' ), + 'description' => __( + 'Support form template. The resulting bridge will notify form submissions on a Zulip stream', + 'forms-bridge' + ), + 'fields' => array( + array( + 'ref' => '#bridge', + 'name' => 'endpoint', + 'value' => '/api/v1/messages', + ), + array( + 'ref' => '#bridge/custom_fields[]', + 'name' => 'to[0]', + 'label' => __( 'Stream', 'forms-bridge' ), + 'description' => __( + 'Name of the stream (channel) where notifications will be sent', + 'forms-bridge' + ), + 'type' => 'select', + 'options' => array( + 'endpoint' => '/api/v1/streams', + 'finger' => array( + 'value' => 'streams[].stream_id', + 'label' => 'streams[].name', + ), + ), + ), + array( + 'ref' => '#form', + 'name' => 'title', + 'default' => __( 'Support', 'forms-bridge' ), + ), + ), + 'form' => array( + 'title' => __( 'Support', 'forms-bridge' ), + 'fields' => array( + array( + 'name' => 'your-name', + 'label' => __( 'Your name', 'forms-bridge' ), + 'type' => 'text', + 'required' => true, + ), + array( + 'name' => 'your-email', + 'label' => __( 'Your email', 'forms-bridge' ), + 'type' => 'email', + 'required' => true, + ), + array( + 'name' => 'topic', + 'label' => __( 'Topic', 'forms-bridge' ), + 'type' => 'select', + 'options' => array( + array( + 'value' => 'A', + 'label' => 'Option 1', + ), + array( + 'value' => 'B', + 'label' => 'Option 2', + ), + ), + 'required' => true, + ), + array( + 'name' => 'comments', + 'label' => __( 'Comments', 'forms-bridge' ), + 'type' => 'textarea', + ), + ), + ), + 'bridge' => array( + 'endpoint' => '/api/v1/messages', + 'custom_fields' => array( + array( + 'name' => 'type', + 'value' => 'stream', + ), + ), + 'mutations' => array( + array( + array( + 'from' => 'to[]', + 'to' => 'to[]', + 'cast' => 'integer', + ), + array( + 'from' => 'your-name', + 'to' => 'content.name', + 'cast' => 'string', + ), + array( + 'from' => 'your-email', + 'to' => 'content.email', + 'cast' => 'string', + ), + array( + 'from' => 'topic', + 'to' => 'content.topic', + 'cast' => 'string', + ), + array( + 'from' => '?comments', + 'to' => 'content.comments', + 'cast' => 'string', + ), + array( + 'from' => 'content', + 'to' => 'content', + 'cast' => 'json', + ), + ), + ), + ), +); From 07a188036462f22c0c61ce061fab36d87e8d4a6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 22:58:28 +0100 Subject: [PATCH 3/8] feat: zuli oas introspection --- .../addons/listmonk/class-listmonk-addon.php | 70 ++++++------ .../nextcloud/class-nextcloud-addon.php | 1 + .../addons/zulip/class-zulip-addon.php | 107 ++++++++++++++++-- 3 files changed, 132 insertions(+), 46 deletions(-) diff --git a/forms-bridge/addons/listmonk/class-listmonk-addon.php b/forms-bridge/addons/listmonk/class-listmonk-addon.php index c595c22e..6ad8a55d 100644 --- a/forms-bridge/addons/listmonk/class-listmonk-addon.php +++ b/forms-bridge/addons/listmonk/class-listmonk-addon.php @@ -159,43 +159,43 @@ public function get_endpoint_schema( $endpoint, $backend, $method = null ) { } } - if ( '/api/subscribers' === $endpoint ) { - return array( - array( - 'name' => 'email', - 'schema' => array( 'type' => 'string' ), - 'required' => true, - ), - array( - 'name' => 'name', - 'schema' => array( 'type' => 'string' ), - ), - array( - 'name' => 'status', - 'schema' => array( 'type' => 'string' ), - ), - array( - 'name' => 'lists', - 'schema' => array( - 'type' => 'array', - 'items' => array( 'type' => 'number' ), - ), - ), - array( - 'name' => 'preconfirm_subscriptions', - 'schema' => array( 'type' => 'boolean' ), - ), - array( - 'name' => 'attribs', - 'schema' => array( - 'type' => 'object', - 'properties' => array(), - ), - ), - ); + if ( '/api/subscribers' !== $endpoint ) { + return array(); } - return array(); + return array( + array( + 'name' => 'email', + 'schema' => array( 'type' => 'string' ), + 'required' => true, + ), + array( + 'name' => 'name', + 'schema' => array( 'type' => 'string' ), + ), + array( + 'name' => 'status', + 'schema' => array( 'type' => 'string' ), + ), + array( + 'name' => 'lists', + 'schema' => array( + 'type' => 'array', + 'items' => array( 'type' => 'number' ), + ), + ), + array( + 'name' => 'preconfirm_subscriptions', + 'schema' => array( 'type' => 'boolean' ), + ), + array( + 'name' => 'attribs', + 'schema' => array( + 'type' => 'object', + 'properties' => array(), + ), + ), + ); } } diff --git a/forms-bridge/addons/nextcloud/class-nextcloud-addon.php b/forms-bridge/addons/nextcloud/class-nextcloud-addon.php index 06ec01bb..e30d4588 100644 --- a/forms-bridge/addons/nextcloud/class-nextcloud-addon.php +++ b/forms-bridge/addons/nextcloud/class-nextcloud-addon.php @@ -62,6 +62,7 @@ static function ( $prune, $bridge ) { 2 ); } + /** * Performs a request against the backend to check the connexion status. * diff --git a/forms-bridge/addons/zulip/class-zulip-addon.php b/forms-bridge/addons/zulip/class-zulip-addon.php index 6a28464b..b9a3434c 100644 --- a/forms-bridge/addons/zulip/class-zulip-addon.php +++ b/forms-bridge/addons/zulip/class-zulip-addon.php @@ -7,6 +7,8 @@ namespace FORMS_BRIDGE; +use Exception; + if ( ! defined( 'ABSPATH' ) ) { exit(); } @@ -20,26 +22,33 @@ class Zulip_Addon extends Addon { /** - * Handles the addon's title. + * Holds the addon's title. * * @var string */ public const TITLE = 'Zulip'; /** - * Handles the addon's name. + * Holds the addon's name. * * @var string */ public const NAME = 'zulip'; /** - * Handles the addon's custom bridge class. + * Holds the addon's custom bridge class. * * @var string */ public const BRIDGE = '\FORMS_BRIDGE\Zulip_Form_Bridge'; + /** + * Holds the Zulip OAS public URL. + * + * @var string + */ + public const OAS_URL = 'https://raw.githubusercontent.com/zulip/zulip/refs/heads/main/zerver/openapi/zulip.yaml'; + /** * Performs a request against the backend to check the connexion status. * @@ -51,7 +60,7 @@ public function ping( $backend ) { $bridge = new Zulip_Form_Bridge( array( 'name' => '__zulip-' . time(), - 'endpoint' => '/api/v1/users', + 'endpoint' => '/api/v1/streams', 'method' => 'GET', 'backend' => $backend, ), @@ -59,7 +68,14 @@ public function ping( $backend ) { ); $response = $bridge->submit(); - return ! is_wp_error( $response ); + + if ( is_wp_error( $response ) ) { + Logger::log( 'Zulip backend ping error response', Logger::ERROR ); + Logger::log( $response, Logger::ERROR ); + return false; + } + + return true; } /** @@ -87,15 +103,84 @@ public function fetch( $endpoint, $backend ) { /** * Performs an introspection of the backend endpoint and returns API fields. * - * @param string $endpoint API endpoint. - * @param string $backend Backend name. + * @param string $endpoint API endpoint. + * @param string $backend Backend name. + * @param string|null $method HTTP method. * * @return array List of fields and content type of the endpoint. */ - public function get_endpoint_schema( $endpoint, $backend ) { - $path = plugin_dir_path( __FILE__ ) . 'data/openapi.json'; - $openapi = OpenAPI::from( $path ); - return $openapi->params( $endpoint ) ?: array(); + public function get_endpoint_schema( $endpoint, $backend, $method = null ) { + if ( function_exists( 'yaml_parse' ) ) { + $response = wp_remote_get( self::OAS_URL ); + + if ( ! is_wp_error( $response ) ) { + $data = yaml_parse( $response['body'] ); + + if ( $data ) { + try { + $oa_explorer = new OpenAPI( $data ); + + $method = strtolower( $method ?? 'post' ); + $path = preg_replace( '', '', $endpoint ); + $source = in_array( $method, array( 'post', 'put', 'patch' ), true ) ? 'body' : 'query'; + $params = $oa_explorer->params( $path, $method, $source ); + + return $params ?: array(); + } catch ( Exception ) { + // do nothing. + } + } + } + } + + if ( '/api/v1/messages' !== $endpoint ) { + return array(); + } + + return array( + array( + 'name' => 'type', + 'schema' => array( + 'type' => 'string', + 'enum' => array( 'direct', 'stream' ), + ), + 'required' => true, + ), + array( + 'name' => 'to', + 'schema' => array( + 'type' => 'array', + 'items' => array( + 'type' => array( 'string', 'integer' ), + ), + ), + 'required' => true, + ), + array( + 'name' => 'content', + 'schema' => array( 'type' => 'string' ), + 'required' => true, + ), + array( + 'name' => 'topic', + 'schema' => array( + 'type' => 'string', + 'default' => '(no topic)', + ), + ), + array( + 'name' => 'queue_id', + 'schema' => array( 'type' => 'string' ), + ), + array( + 'name' => 'local_id', + 'schema' => array( 'type' => 'string' ), + ), + array( + 'name' => 'read_by_sender', + 'schema' => array( 'type' => 'boolean' ), + ), + ); } } From ea3a7ae9f206dd211cabc48e630dd5119f73dfe5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 22:58:45 +0100 Subject: [PATCH 4/8] feat: zulip uploads --- .../addons/zulip/class-zulip-form-bridge.php | 55 ++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/forms-bridge/addons/zulip/class-zulip-form-bridge.php b/forms-bridge/addons/zulip/class-zulip-form-bridge.php index 804269b2..36cda05f 100644 --- a/forms-bridge/addons/zulip/class-zulip-form-bridge.php +++ b/forms-bridge/addons/zulip/class-zulip-form-bridge.php @@ -7,6 +7,10 @@ namespace FORMS_BRIDGE; +use FBAPI; +use HTTP_BRIDGE\Backend; +use WP_Error; + if ( ! defined( 'ABSPATH' ) ) { exit(); } @@ -14,4 +18,53 @@ /** * Form bridge implamentation for the Zulip API. */ -class Zulip_Form_Bridge extends Form_Bridge {} +class Zulip_Form_Bridge extends Form_Bridge { + + /** + * Submits payload and attachments to the bridge's backend. + * + * @param array $payload Payload data. + * @param array $attachments Submission's attached files. + * + * @return array|WP_Error Http request response. + */ + public function submit( $payload = array(), $attachments = array() ) { + $uploads = FBAPI::get_uploads(); + + if ( ! empty( $uploads ) ) { + $backend = $this->backend()->clone( + array( + 'headers' => array( + array( + 'name' => 'Content-Type', + 'value' => 'multipart/form-data', + ), + ), + ) + ); + + $annex = "\n\n----\n" . esc_html( __( 'Attachments', 'forms-bridge' ) ) . ":\n"; + + $attachments = Forms_Bridge::attachments( $uploads ); + + foreach ( $attachments as $name => $path ) { + $response = $backend->post( '/api/v1/user_uploads', array(), array(), array( $name => $path ) ); + + if ( is_wp_error( $response ) ) { + return $response; + } elseif ( 'success' !== $response['data']['result'] ) { + return new WP_Error( 'zulip_upload', __( 'Can not upload a file to Zulip', 'forms-bridge' ), $response['data'] ); + } + + unset( $payload[ $name ] ); + unset( $payload[ $name . '_filename' ] ); + + $annex .= "* [{$name}]({$response['data']['url']})\n"; + } + + $payload['content'] .= $annex; + } + + return parent::submit( $payload, array() ); + } +} From de989d3428dcba76bf6a48ee655ee035440eaa49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 22:59:43 +0100 Subject: [PATCH 5/8] fix: backend content type on zulip templates --- forms-bridge/addons/zulip/hooks.php | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/forms-bridge/addons/zulip/hooks.php b/forms-bridge/addons/zulip/hooks.php index 26a242e9..0c7408ce 100644 --- a/forms-bridge/addons/zulip/hooks.php +++ b/forms-bridge/addons/zulip/hooks.php @@ -5,7 +5,6 @@ * @package formsbridge */ - if ( ! defined( 'ABSPATH' ) ) { exit(); } @@ -39,6 +38,11 @@ function ( $defaults, $addon, $schema ) { 'type' => 'url', 'default' => 'https://your-organization.zulipchat.com', ), + array( + 'ref' => '#backend/headers[]', + 'name' => 'Content-Type', + 'value' => 'application/x-www-form-urlencoded', + ), array( 'ref' => '#credential', 'name' => 'name', @@ -81,7 +85,13 @@ function ( $defaults, $addon, $schema ) { 'method' => 'POST', ), 'backend' => array( - 'name' => 'Zulip API', + 'name' => 'Zulip API', + 'headers' => array( + array( + 'name' => 'Content-Type', + 'value' => 'application/x-www-form-urlencoded', + ), + ), ), 'credential' => array( 'name' => '', From 1eaaec6ca80a3dd6fffd860b8e491d709ca56d81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 23:00:47 +0100 Subject: [PATCH 6/8] feat: cast as pretty json --- forms-bridge/includes/class-form-bridge.php | 13 ++++++++++--- forms-bridge/includes/class-forms-bridge.php | 7 +++---- src/components/Mutations/Layers.jsx | 4 ++++ 3 files changed, 17 insertions(+), 7 deletions(-) diff --git a/forms-bridge/includes/class-form-bridge.php b/forms-bridge/includes/class-form-bridge.php index d410b0cc..4ebf9c95 100644 --- a/forms-bridge/includes/class-form-bridge.php +++ b/forms-bridge/includes/class-form-bridge.php @@ -163,6 +163,7 @@ public static function schema( $addon = null ) { 'or', 'xor', 'json', + 'pretty_json', 'csv', 'concat', 'join', @@ -558,11 +559,17 @@ private function cast( $value, $mapper ) { false ); case 'json': - if ( ! is_array( $value ) ) { - return ''; + if ( is_array( $value ) || is_object( $value ) ) { + return wp_json_encode( (array) $value, JSON_UNESCAPED_UNICODE ); + } + + return $value; + case 'pretty_json': + if ( is_array( $value ) || is_object( $value ) ) { + return wp_json_encode( (array) $value, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT ); } - return wp_json_encode( $value, JSON_UNESCAPED_UNICODE ); + return $value; case 'csv': if ( ! wp_is_numeric_array( $value ) ) { return ''; diff --git a/forms-bridge/includes/class-forms-bridge.php b/forms-bridge/includes/class-forms-bridge.php index b945d3cd..599b312a 100644 --- a/forms-bridge/includes/class-forms-bridge.php +++ b/forms-bridge/includes/class-forms-bridge.php @@ -312,12 +312,11 @@ function ( $field ) { true ) ) { - $attachments = self::stringify_attachments( - $attachments - ); + $attachments = self::stringify_attachments( $attachments ); foreach ( $attachments as $name => $value ) { $submission[ $name ] = $value; } + $attachments = array(); Logger::log( 'Submission after attachments stringify' ); Logger::log( $submission ); @@ -467,7 +466,7 @@ private static function prune_empties( $submission_data ) { * * @return array Map of uploaded files. */ - private static function attachments( $uploads ) { + public static function attachments( $uploads ) { $attachments = array(); foreach ( $uploads as $name => $upload ) { diff --git a/src/components/Mutations/Layers.jsx b/src/components/Mutations/Layers.jsx index ba378612..e0633ded 100644 --- a/src/components/Mutations/Layers.jsx +++ b/src/components/Mutations/Layers.jsx @@ -42,6 +42,10 @@ const castOptions = [ value: "json", label: "JSON", }, + { + value: "pretty_json", + label: "Pretty JSON", + }, { value: "csv", label: "CSV", From 0bdb85f7c452b661cc81d74b92a70c1e9b03db61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 23:01:01 +0100 Subject: [PATCH 7/8] feat: zulip templates --- .../addons/zulip/templates/contact.php | 121 ++++++++++++++++++ .../addons/zulip/templates/direct-message.php | 108 ++++++++++++++++ .../addons/zulip/templates/support.php | 14 +- 3 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 forms-bridge/addons/zulip/templates/contact.php create mode 100644 forms-bridge/addons/zulip/templates/direct-message.php diff --git a/forms-bridge/addons/zulip/templates/contact.php b/forms-bridge/addons/zulip/templates/contact.php new file mode 100644 index 00000000..0cd89563 --- /dev/null +++ b/forms-bridge/addons/zulip/templates/contact.php @@ -0,0 +1,121 @@ + __( 'Contacts', 'forms-bridge' ), + 'description' => __( + 'Contact form template. The resulting bridge will notify form submissions in a Zulip stream', + 'forms-bridge' + ), + 'fields' => array( + array( + 'ref' => '#bridge', + 'name' => 'endpoint', + 'value' => '/api/v1/messages', + ), + array( + 'ref' => '#bridge/custom_fields[]', + 'name' => 'to[0]', + 'label' => __( 'Stream', 'forms-bridge' ), + 'description' => __( + 'Name of the stream (channel) where notifications will be sent', + 'forms-bridge' + ), + 'type' => 'select', + 'options' => array( + 'endpoint' => '/api/v1/streams', + 'finger' => array( + 'value' => 'streams[].stream_id', + 'label' => 'streams[].name', + ), + ), + ), + array( + 'ref' => '#bridge/custom_fields[]', + 'name' => 'topic', + 'label' => __( 'Topic', 'forms-bridge' ), + 'description' => __( 'Topic under which the messages will be notified', 'forms-bridge' ), + 'type' => 'text', + 'default' => 'WordPress', + 'required' => true, + ), + array( + 'ref' => '#form', + 'name' => 'title', + 'default' => __( 'Contacts', 'forms-bridge' ), + ), + ), + 'form' => array( + 'title' => __( 'Contacts', 'forms-bridge' ), + 'fields' => array( + array( + 'name' => 'your-name', + 'label' => __( 'Your name', 'forms-bridge' ), + 'type' => 'text', + 'required' => true, + ), + array( + 'name' => 'your-email', + 'label' => __( 'Your email', 'forms-bridge' ), + 'type' => 'email', + 'required' => true, + ), + array( + 'name' => 'comments', + 'label' => __( 'Comments', 'forms-bridge' ), + 'type' => 'textarea', + ), + ), + ), + 'bridge' => array( + 'endpoint' => '/api/v1/messages', + 'custom_fields' => array( + array( + 'name' => 'type', + 'value' => 'stream', + ), + ), + 'mutations' => array( + array( + array( + 'from' => 'to[]', + 'to' => 'to[]', + 'cast' => 'integer', + ), + array( + 'from' => 'to', + 'to' => 'to', + 'cast' => 'json', + ), + array( + 'from' => 'your-name', + 'to' => 'content.name', + 'cast' => 'string', + ), + array( + 'from' => 'your-email', + 'to' => 'content.email', + 'cast' => 'string', + ), + array( + 'from' => '?comments', + 'to' => 'content.comments', + 'cast' => 'string', + ), + array( + 'from' => 'content', + 'to' => 'content', + 'cast' => 'pretty_json', + ), + ), + ), + ), +); diff --git a/forms-bridge/addons/zulip/templates/direct-message.php b/forms-bridge/addons/zulip/templates/direct-message.php new file mode 100644 index 00000000..1a176283 --- /dev/null +++ b/forms-bridge/addons/zulip/templates/direct-message.php @@ -0,0 +1,108 @@ + __( 'Direct Messages', 'forms-bridge' ), + 'description' => __( + 'Contact form template. The resulting bridge will send form submissions as direct messages on Zulip', + 'forms-bridge' + ), + 'fields' => array( + array( + 'ref' => '#bridge', + 'name' => 'endpoint', + 'value' => '/api/v1/messages', + ), + array( + 'ref' => '#bridge/custom_fields[]', + 'name' => 'to[0]', + 'label' => __( 'User', 'forms-bridge' ), + 'type' => 'select', + 'options' => array( + 'endpoint' => '/api/v1/users', + 'finger' => array( + 'value' => 'members[].user_id', + 'label' => 'members[].delivery_email', + ), + ), + ), + array( + 'ref' => '#form', + 'name' => 'title', + 'default' => __( 'Direct Messages', 'forms-bridge' ), + ), + ), + 'form' => array( + 'title' => __( 'Direct Messages', 'forms-bridge' ), + 'fields' => array( + array( + 'name' => 'your-name', + 'label' => __( 'Your name', 'forms-bridge' ), + 'type' => 'text', + 'required' => true, + ), + array( + 'name' => 'your-email', + 'label' => __( 'Your email', 'forms-bridge' ), + 'type' => 'email', + 'required' => true, + ), + array( + 'name' => 'comments', + 'label' => __( 'Comments', 'forms-bridge' ), + 'type' => 'textarea', + ), + ), + ), + 'bridge' => array( + 'endpoint' => '/api/v1/messages', + 'custom_fields' => array( + array( + 'name' => 'type', + 'value' => 'direct', + ), + ), + 'mutations' => array( + array( + array( + 'from' => 'to[]', + 'to' => 'to[]', + 'cast' => 'integer', + ), + array( + 'from' => 'to', + 'to' => 'to', + 'cast' => 'json', + ), + array( + 'from' => 'your-name', + 'to' => 'content.name', + 'cast' => 'string', + ), + array( + 'from' => 'your-email', + 'to' => 'content.email', + 'cast' => 'string', + ), + array( + 'from' => '?comments', + 'to' => 'content.comments', + 'cast' => 'string', + ), + array( + 'from' => 'content', + 'to' => 'content', + 'cast' => 'pretty_json', + ), + ), + ), + ), +); diff --git a/forms-bridge/addons/zulip/templates/support.php b/forms-bridge/addons/zulip/templates/support.php index b3b709ea..c4f21da1 100644 --- a/forms-bridge/addons/zulip/templates/support.php +++ b/forms-bridge/addons/zulip/templates/support.php @@ -12,7 +12,7 @@ return array( 'title' => __( 'Support Stream', 'forms-bridge' ), 'description' => __( - 'Support form template. The resulting bridge will notify form submissions on a Zulip stream', + 'Support form template. The resulting bridge will notify form submissions in a Zulip stream', 'forms-bridge' ), 'fields' => array( @@ -97,6 +97,11 @@ 'to' => 'to[]', 'cast' => 'integer', ), + array( + 'from' => 'to', + 'to' => 'to', + 'cast' => 'json', + ), array( 'from' => 'your-name', 'to' => 'content.name', @@ -107,11 +112,6 @@ 'to' => 'content.email', 'cast' => 'string', ), - array( - 'from' => 'topic', - 'to' => 'content.topic', - 'cast' => 'string', - ), array( 'from' => '?comments', 'to' => 'content.comments', @@ -120,7 +120,7 @@ array( 'from' => 'content', 'to' => 'content', - 'cast' => 'json', + 'cast' => 'pretty_json', ), ), ), From 6f1d0146918bf37cce9d8eacf9b2b7d3e8d84abf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= Date: Tue, 18 Nov 2025 23:04:10 +0100 Subject: [PATCH 8/8] feat: remove static openapi zulip data --- .../addons/zulip/class-zulip-form-bridge.php | 1 - forms-bridge/addons/zulip/data/openapi.json | 23894 ---------------- .../addons/zulip/templates/contact.php | 4 +- 3 files changed, 2 insertions(+), 23897 deletions(-) delete mode 100644 forms-bridge/addons/zulip/data/openapi.json diff --git a/forms-bridge/addons/zulip/class-zulip-form-bridge.php b/forms-bridge/addons/zulip/class-zulip-form-bridge.php index 36cda05f..0e0a66b9 100644 --- a/forms-bridge/addons/zulip/class-zulip-form-bridge.php +++ b/forms-bridge/addons/zulip/class-zulip-form-bridge.php @@ -8,7 +8,6 @@ namespace FORMS_BRIDGE; use FBAPI; -use HTTP_BRIDGE\Backend; use WP_Error; if ( ! defined( 'ABSPATH' ) ) { diff --git a/forms-bridge/addons/zulip/data/openapi.json b/forms-bridge/addons/zulip/data/openapi.json deleted file mode 100644 index ad2700e9..00000000 --- a/forms-bridge/addons/zulip/data/openapi.json +++ /dev/null @@ -1,23894 +0,0 @@ -{ - "openapi": "3.0.1", - "info": { - "version": "1.0.0", - "title": "Zulip REST API", - "description": "Powerful open source group chat\n", - "contact": { - "url": "https://zulip.com" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "servers": [ - { - "url": "https://{subdomain}.zulipchat.com/api/v1", - "variables": { - "subdomain": { - "default": "example" - } - } - }, - { - "url": "{server}/api/v1", - "variables": { - "server": { - "default": "https://" - } - } - }, - { - "url": "https://chat.zulip.org/api/v1" - }, - { - "url": "http://localhost:9991/api/v1" - }, - { - "url": "http://{subdomain}.testserver/json" - } - ], - "security": [ - { - "basicAuth": [] - } - ], - "paths": { - "/fetch_api_key": { - "post": { - "operationId": "fetch-api-key", - "summary": "Fetch an API key (production)", - "tags": ["authentication"], - "description": "This API endpoint is used by clients such as the Zulip mobile and\nterminal apps to implement password-based authentication. Given the\nuser's Zulip login credentials, it returns a Zulip API key that the client\ncan use to make requests as the user.\n\nThis endpoint is only useful for Zulip servers/organizations with\nEmailAuthBackend or LDAPAuthBackend enabled.\n\nThe Zulip mobile apps also support SSO/social authentication (GitHub\nauth, Google auth, SAML, etc.) that does not use this endpoint. Instead,\nthe mobile apps reuse the web login flow passing the `mobile_flow_otp` in\na webview, and the credentials are returned to the app (encrypted) via a redirect\nto a `zulip://` URL.\n\n!!! warn \"\"\n\n **Note:** If you signed up using passwordless authentication and\n never had a password, you can [reset your password](/help/change-your-password).\n\nSee the [API keys](/api/api-keys) documentation for more details\non how to download an API key manually.\n\nIn a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),\nsee also [the unauthenticated variant](/api/dev-fetch-api-key).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "username": { - "description": "The username to be used for authentication (typically, the email\naddress, but depending on configuration, it could be an LDAP username).\n\nSee the `require_email_format_usernames` parameter documented in\n[GET /server_settings](/api/get-server-settings) for details.\n", - "type": "string", - "example": "iago@zulip.com" - }, - "password": { - "type": "string", - "example": "abcd1234", - "description": "The user's Zulip password (or LDAP password, if LDAP authentication is in use).\n" - } - }, - "required": ["username", "password"] - } - } - } - }, - "security": [], - "responses": { - "200": { - "description": "Valid credentials the client can use to access the Zulip API:\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiKeyResponse" - } - } - } - } - } - } - }, - "/dev_fetch_api_key": { - "post": { - "operationId": "dev-fetch-api-key", - "summary": "Fetch an API key (development only)", - "tags": ["authentication"], - "description": "For easy testing of mobile apps and other clients and against Zulip\ndevelopment servers, we support fetching a Zulip API key for any user\non the development server without authentication (so that they can\nimplement analogues of the one-click login process available for Zulip\ndevelopment servers on the web).\n\n!!! warn \"\"\n\n **Note:** This endpoint is only available on Zulip development\n servers; for obvious security reasons it will always return an error\n in a Zulip production server.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "username": { - "description": "The email address for the user that owns the API key.\n", - "type": "string", - "example": "iago@zulip.com" - } - }, - "required": ["username"] - } - } - } - }, - "security": [], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiKeyResponse" - } - } - } - } - } - } - }, - "/events": { - "get": { - "operationId": "get-events", - "summary": "Get events from an event queue", - "tags": ["real_time_events"], - "description": "This endpoint allows you to receive new events from\n[a registered event queue](/api/register-queue).\n\nLong-lived clients should use the\n`event_queue_longpoll_timeout_seconds` property returned by\n`POST /register` as the client-side HTTP request timeout for\ncalls to this endpoint. It is guaranteed to be higher than\nheartbeat frequency and should be respected by clients to\navoid breaking when heartbeat frequency increases.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["queue_id", "last_event_id"] - } - } - ] - }, - "x-parameter-description": "!!! warn \"\"\n\n **Note**: The parameters documented above are optional in the sense that\n even if you haven't registered a queue by explicitly requesting the\n `POST /register` endpoint, you could pass the parameters for\n [the `POST /register` endpoint](/api/register-queue) to this\n endpoint and a queue would be registered in the absence of a `queue_id`.\n", - "x-python-examples-extra-imports": ["sys"], - "parameters": [ - { - "$ref": "#/components/parameters/QueueId" - }, - { - "name": "last_event_id", - "in": "query", - "description": "The highest event ID in this queue that you've received and\nwish to acknowledge. See the [code for\n`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)\nin the [zulip Python\nmodule](https://github.com/zulip/python-zulip-api) for an\nexample implementation of correctly processing each event\nexactly once.\n", - "schema": { - "type": "integer" - }, - "example": -1 - }, - { - "name": "dont_block", - "in": "query", - "description": "Set to `true` if the client is requesting a nonblocking reply. If not\nspecified, the request will block until either a new event is available\nor a few minutes have passed, in which case the server will send the\nclient a heartbeat event.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "events": { - "type": "array", - "description": "An array of `event` objects (possibly zero-length if `dont_block` is\nset) with IDs newer than `last_event_id`. Event IDs are\nguaranteed to be increasing, but they are not guaranteed to be\nconsecutive.\n", - "items": { - "oneOf": [ - { - "type": "object", - "description": "Event sent to a user's clients when that user's set of configured\n[alert words](/help/dm-mention-alert-notifications#alert-words) have changed.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["alert_words"] - } - ] - }, - "alert_words": { - "type": "array", - "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", - "items": { - "type": "string" - } - } - }, - "additionalProperties": false, - "example": { - "type": "alert_words", - "alert_words": ["alert_word"], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to clients that have requested the\n`update_display_settings` event type and did not include\n`user_settings_object` in their `client_capabilities` when\nregistering the event queue.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and process the `user_settings` event type instead.\n", - "deprecated": true, - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["update_display_settings"] - } - ] - }, - "user": { - "type": "string", - "description": "The Zulip API email of the user.\n" - }, - "setting_name": { - "type": "string", - "description": "Name of the changed display setting.\n" - }, - "setting": { - "description": "New value of the changed setting.\n", - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "integer" - }, - { - "type": "string" - } - ] - }, - "language_name": { - "description": "Present only if the setting to be changed is\n`default_language`. Contains the name of the\nnew default language in English.\n", - "type": "string" - } - }, - "additionalProperties": false, - "example": { - "type": "update_display_settings", - "user": "iago@zulip.com", - "setting_name": "high_contrast_mode", - "setting": false, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user's [notification\nsettings](/api/update-settings) have changed with an additional\nrule that it is only sent to clients that did not include\n`user_settings_object` in their `client_capabilities` when\nregistering the event queue.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and process the `user_settings` event type instead.\n", - "deprecated": true, - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["update_global_notifications"] - } - ] - }, - "user": { - "type": "string", - "description": "The Zulip API email of the user.\n" - }, - "notification_name": { - "type": "string", - "description": "Name of the changed notification setting.\n" - }, - "setting": { - "description": "New value of the changed setting.\n", - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "integer" - }, - { - "type": "string" - } - ] - } - }, - "additionalProperties": false, - "example": { - "type": "update_global_notifications", - "user": "iago@zulip.com", - "notification_name": "enable_sounds", - "setting": true, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user's settings\nhave changed.\n\n**Changes**: New in Zulip 5.0 (feature level 89), replacing the\nprevious `update_display_settings` and `update_global_notifications`\nevent types, which are still present for backwards compatibility reasons.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_settings"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "property": { - "type": "string", - "description": "Name of the changed setting.\n" - }, - "value": { - "description": "New value of the changed setting.\n", - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "integer" - }, - { - "type": "string" - } - ] - }, - "language_name": { - "description": "Present only if the setting to be changed is\n`default_language`. Contains the name of the\nnew default language in English.\n", - "type": "string" - } - }, - "additionalProperties": false, - "example": { - "type": "user_settings", - "op": "update", - "property": "high_contrast_mode", - "value": false, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent generally to all users who can access the modified\nuser for changes in the set of users or those users metadata.\n\n**Changes**: Prior to Zulip 8.0 (feature level 228), this event\nwas sent to all users in the organization.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_user"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "person": { - "description": "Object containing the changed details of the user.\nIt has multiple forms depending on the value changed.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0\n(feature level 363), as it was replaced by the\n`can_manage_billing_group` realm setting.\n", - "oneOf": [ - { - "type": "object", - "description": "When a user changes their full name.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of modified user.\n" - }, - "full_name": { - "type": "string", - "description": "The new full name for the user.\n" - } - }, - "additionalProperties": false - }, - { - "type": "object", - "description": "When a user changes their avatar.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user who is affected by this change.\n" - }, - "avatar_url": { - "type": "string", - "description": "The URL of the new avatar for the user.\n" - }, - "avatar_source": { - "type": "string", - "description": "The new avatar data source type for the user.\n\nValue values are `G` (gravatar) and `U` (uploaded by user).\n" - }, - "avatar_url_medium": { - "type": "string", - "description": "The new medium-size avatar URL for user.\n" - }, - "avatar_version": { - "type": "integer", - "description": "The version number for the user's avatar. This is useful\nfor cache-busting.\n" - } - }, - "additionalProperties": false - }, - { - "type": "object", - "additionalProperties": false, - "description": "When a user changes their [profile time zone](/help/change-your-timezone).\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of modified user.\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email of the user.\n\n**Deprecated**: This field will be removed in a future\nrelease as it is redundant with the `user_id`.\n", - "deprecated": true - }, - "timezone": { - "type": "string", - "description": "The IANA identifier of the new profile time zone for the user.\n" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the owner of a bot changes.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user/bot whose owner has changed.\n" - }, - "bot_owner_id": { - "type": "integer", - "description": "The user ID of the new bot owner.\n" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the [role](/help/user-roles) of a user changes.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user affected by this change.\n" - }, - "role": { - "type": "integer", - "description": "The new [role](/api/roles-and-permissions) of the user.\n", - "enum": [100, 200, 300, 400, 600] - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the value of a user's delivery email as visible to you changes,\neither due to the email address changing or your access to the user's\nemail changing via an update to their `email_address_visibility`\nsetting.\n\n**Changes**: Prior to Zulip 7.0 (feature level 163), this event was\nsent only to the affected user, and this event would only be triggered\nby changing the affected user's delivery email.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user affected by this change.\n" - }, - "delivery_email": { - "type": "string", - "nullable": true, - "description": "The new delivery email of the user.\n\nThis value can be `null` if the affected user\nchanged their `email_address_visibility` setting\nsuch that you cannot access their real email.\n\n**Changes**: Before Zulip 7.0 (feature level 163),\n`null` was not a possible value for this event as\nit was only sent to the affected user when their\nemail address was changed.\n" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the user updates one of their custom profile\nfields.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user affected by this change.\n" - }, - "custom_profile_field": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details about the custom\nprofile data change.\n", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the custom profile field which user updated.\n" - }, - "value": { - "type": "string", - "nullable": true, - "description": "User's personal value for this custom profile field,\nor `null` if unset.\n" - }, - "rendered_value": { - "type": "string", - "description": "The `value` rendered in HTML. Will only be present for\ncustom profile field types that support Markdown rendering.\n\nThis user-generated HTML content should be rendered\nusing the same CSS and client-side security protections\nas are used for message content.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - } - } - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the Zulip API email address of a user changes,\neither due to the user's email address changing, or\ndue to changes in the user's\n[email address visibility][help-email-visibility].\n\n[help-email-visibility]: /help/configure-email-visibility\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user affected by this change.\n" - }, - "new_email": { - "type": "string", - "description": "The new value of `email` for the user. The client\nshould update any data structures associated\nwith this user to use this new value as the\nuser's Zulip API email address.\n" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When a user is deactivated or reactivated. Only\nusers who can access the modified user under the\norganization's `can_access_all_users_group` policy\nwill receive this event.\n\nClients receiving a deactivation event should\nremove the user from all user groups in their data\nstructures, because deactivated users cannot be\nmembers of groups.\n\n**Changes**: Prior to Zulip 10.0 (feature level\n303), reactivation events were sent to users who\ncould not access the reactivated user due to a\n`can_access_all_users_group` policy. Also,\npreviously, Clients were not required to update\ngroup membership records during user deactivation.\n\nNew in Zulip 8.0 (feature level 222). Previously the server\nsent a `realm_user` event with `op` field set to `remove`\nwhen deactivating a user and a `realm_user` event with `op`\nfield set to `add` when reactivating a user.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user affected by this change.\n" - }, - "is_active": { - "type": "boolean", - "description": "A boolean describing whether the user account has been deactivated.\n" - } - } - } - ] - } - }, - "additionalProperties": false, - "example": { - "type": "realm_user", - "op": "update", - "person": { - "avatar_source": "G", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3", - "avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3", - "avatar_version": 3, - "user_id": 10 - }, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user's channel subscriptions\nhave changed (either the set of subscriptions or their properties).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["subscription"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "subscriptions": { - "type": "array", - "description": "A list of dictionaries where each dictionary contains\ninformation about one of the subscribed channels.\n\n**Changes**: Removed `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n", - "items": { - "$ref": "#/components/schemas/Subscription" - } - } - }, - "additionalProperties": false, - "example": { - "type": "subscription", - "op": "add", - "subscriptions": [ - { - "name": "test", - "stream_id": 9, - "is_archived": false, - "creator_id": null, - "description": "", - "rendered_description": "", - "invite_only": false, - "is_web_public": false, - "stream_post_policy": 1, - "history_public_to_subscribers": true, - "first_message_id": null, - "folder_id": 1, - "is_recently_active": true, - "message_retention_days": null, - "is_announcement_only": false, - "color": "#76ce90", - "is_muted": false, - "pin_to_top": false, - "audible_notifications": null, - "desktop_notifications": null, - "email_notifications": null, - "push_notifications": null, - "wildcard_mentions_notify": null, - "in_home_view": true, - "stream_weekly_traffic": null, - "can_add_subscribers_group": 2, - "can_remove_subscribers_group": 2, - "can_subscribe_group": 2, - "subscribers": [10] - } - ], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user has been unsubscribed\nfrom one or more channels.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["subscription"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "subscriptions": { - "type": "array", - "description": "A list of dictionaries, where each dictionary contains\ninformation about one of the newly unsubscribed channels.\n", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Dictionary containing details about the unsubscribed channel.\n", - "properties": { - "stream_id": { - "type": "integer", - "description": "The ID of the channel.\n" - }, - "name": { - "type": "string", - "description": "The name of the channel.\n" - } - } - } - } - }, - "additionalProperties": false, - "example": { - "type": "subscription", - "op": "remove", - "subscriptions": [ - { - "name": "test", - "stream_id": 9 - } - ], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when a property of the user's\nsubscription to a channel has been updated. This event is used\nonly for personal properties like `is_muted` or `pin_to_top`.\nSee the [`stream op: update` event](/api/get-events#stream-update)\nfor updates to global properties of a channel.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["subscription"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "stream_id": { - "type": "integer", - "description": "The ID of the channel whose subscription details have changed.\n" - }, - "property": { - "type": "string", - "description": "The property of the subscription which has changed. For details on the\nvarious subscription properties that a user can change, see\n[POST /users/me/subscriptions/properties](/api/update-subscription-settings).\n\nClients should generally handle an unknown property received here without\ncrashing, since that will naturally happen when connecting to a Zulip\nserver running a new version that adds a new subscription property.\n\n**Changes**: As of Zulip 6.0 (feature level 139), updates to the `is_muted`\nproperty or the deprecated `in_home_view` property will send two `subscription`\nupdate events, one for each property, to support clients fully migrating to\nuse the `is_muted` property. Prior to this feature level, updates to either\nproperty only sent one event with the deprecated `in_home_view` property.\n" - }, - "value": { - "description": "The new value of the changed property.\n", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - }, - { - "type": "string" - } - ] - } - }, - "additionalProperties": false, - "example": { - "op": "update", - "type": "subscription", - "property": "pin_to_top", - "value": true, - "stream_id": 11, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent when another user subscribes to a channel, or their\nsubscription is newly visible to the current user.\n\nWhen a user subscribes to a channel, the current user will receive this\nevent only if they [have permission to see the channel's subscriber\nlist](/help/channel-permissions). When the current user gains permission\nto see a given channel's subscriber list, they will receive this event\nfor the existing subscriptions to the channel.\n\n**Changes**: Prior to Zulip 8.0 (feature level 220), this event was\nincorrectly not sent to guest users when subscribers to web-public\nchannels and subscribed public channels changed.\n\nPrior to Zulip 8.0 (feature level 205), this event was not sent when\na user gained access to a channel due to their [role\nchanging](/help/user-roles).\n\nPrior to Zulip 6.0 (feature level 134), this event was not sent when a\nprivate channel was made public.\n\nIn Zulip 4.0 (feature level 35), the singular `user_id` and `stream_id`\nintegers included in this event were replaced with plural `user_ids` and\n`stream_ids` integer arrays.\n\nIn Zulip 3.0 (feature level 19), the `stream_id` field was added to\nidentify the channel the user subscribed to, replacing the `name` field.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["subscription"] - } - ] - }, - "op": { - "type": "string", - "enum": ["peer_add"] - }, - "stream_ids": { - "type": "array", - "description": "The IDs of channels that have new or updated subscriber data.\n\n**Changes**: New in Zulip 4.0 (feature level 35), replacing\nthe `stream_id` integer.\n", - "items": { - "type": "integer" - } - }, - "user_ids": { - "type": "array", - "description": "The IDs of the users who are newly visible as subscribed to\nthe specified channels.\n\n**Changes**: New in Zulip 4.0 (feature level 35), replacing\nthe `user_id` integer.\n", - "items": { - "type": "integer" - } - } - }, - "additionalProperties": false, - "example": { - "type": "subscription", - "op": "peer_add", - "stream_ids": [9], - "user_ids": [12], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to other users when users have been unsubscribed\nfrom channels. Sent to all users if the channel is public or to only\nthe existing subscribers if the channel is private.\n\n**Changes**: Prior to Zulip 8.0 (feature level 220), this event was\nincorrectly not sent to guest users when subscribers to web-public\nchannels and subscribed public channels changed.\n\nIn Zulip 4.0 (feature level 35), the singular `user_id` and\n`stream_id` integers included in this event were replaced\nwith plural `user_ids` and `stream_ids` integer arrays.\n\nIn Zulip 3.0 (feature level 19), the `stream_id` field was\nadded to identify the channel the user unsubscribed from,\nreplacing the `name` field.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["subscription"] - } - ] - }, - "op": { - "type": "string", - "enum": ["peer_remove"] - }, - "stream_ids": { - "type": "array", - "description": "The IDs of the channels from which the users have been\nunsubscribed from.\n\nWhen a user is deactivated, the server will send this event\nremoving the user's subscriptions before the `realm_user` event\nfor the user's deactivation.\n\n**Changes**: Before Zulip 10.0 (feature level 377), this event\nwas not sent on user deactivation. Clients supporting older\nserver versions and maintaining peer subscriber data need to\nremove all channel subscriptions for a user when processing the\n`realm_user` event with `op=\"remove\"`.\n\n**Changes**: New in Zulip 4.0 (feature level 35), replacing\nthe `stream_id` integer.\n", - "items": { - "type": "integer" - } - }, - "user_ids": { - "type": "array", - "description": "The IDs of the users who have been unsubscribed.\n\n**Changes**: New in Zulip 4.0 (feature level 35), replacing\nthe `user_id` integer.\n", - "items": { - "type": "integer" - } - } - }, - "additionalProperties": false, - "example": { - "type": "subscription", - "op": "peer_remove", - "stream_ids": [9], - "user_ids": [12], - "id": 0 - } - }, - { - "type": "object", - "description": "Event type for messages.\n\n**Changes**: In Zulip 3.1 (feature level 26), the\n`sender_short_name` field was removed from message\nobjects.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["message"] - } - ] - }, - "message": { - "$ref": "#/components/schemas/MessagesEvent" - }, - "flags": { - "type": "array", - "description": "The user's [message flags][message-flags] for the message.\n\nClients should inspect the flags field rather than assuming that\nnew messages are unread; [muted users](/api/mute-user), messages\nsent by the current user, and more subtle scenarios can result\nin a new message that the server has already marked as read for\nthe user.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", - "items": { - "type": "string" - } - } - }, - "additionalProperties": false, - "example": { - "type": "message", - "message": { - "id": 31, - "sender_id": 10, - "content": "

First message ...zulip.txt

", - "recipient_id": 23, - "timestamp": 1594825416, - "client": "test suite", - "subject": "test", - "topic_links": [], - "is_me_message": false, - "reactions": [], - "submessages": [], - "sender_full_name": "King Hamlet", - "sender_email": "user10@zulip.testserver", - "sender_realm_str": "zulip", - "display_recipient": "Denmark", - "type": "stream", - "stream_id": 1, - "avatar_url": null, - "content_type": "text/html" - }, - "flags": [], - "id": 1 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when the user completes the OAuth flow\nfor the [Zoom integration](/help/configure-call-provider). Clients need\nto know whether initiating Zoom OAuth is required before creating a Zoom\ncall.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["has_zoom_token"] - } - ] - }, - "value": { - "type": "boolean", - "description": "A boolean specifying whether the user has zoom\ntoken or not.\n" - } - }, - "additionalProperties": false, - "example": { - "type": "has_zoom_token", - "value": true, - "id": 0 - } - }, - { - "type": "object", - "description": "A simple event sent when the set of invitations changes.\nThis event is sent to organization administrators and the creator of\nthe changed invitation; this tells clients they need to refetch\ndata from `GET /invites` if they are displaying UI containing active\ninvitations.\n\n**Changes**: Before Zulip 8.0 (feature level 209), this event was\nonly sent to organization administrators.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["invites_changed"] - } - ] - } - }, - "additionalProperties": false, - "example": { - "type": "invites_changed", - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to all users in a Zulip organization when a new\nuser joins or when a guest user gains access to a user.\nProcessing this event is important to being able to display\nbasic details on other users given only their ID.\n\nIf the current user is a guest whose access to a newly created user\nis limited by a `can_access_all_users_group` policy, and the event\nqueue was registered with the `user_list_incomplete` client\ncapability, then the event queue will not receive an event for such\na new user. If a newly created user is inaccessible to the current\nuser via such a policy, but the client lacks `user_list_incomplete`\nclient capability, then this event will be delivered to the queue,\nwith an \"Unknown user\" object with the usual format but placeholder\ndata whose only variable content is the user ID.\n\n**Changes**: Before Zulip 8.0 (feature level 232), the\n`user_list_incomplete` client capability did not exist, and so all\nclients whose access to a new user was prevented by\n`can_access_all_users_group` policy would receive a fake \"Unknown\nuser\" event for such a user.\n\nStarting with Zulip 8.0 (feature level 228),\nthis event is also sent when a guest user gains access to\na user.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_user"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "person": { - "$ref": "#/components/schemas/User" - } - }, - "additionalProperties": false, - "example": { - "type": "realm_user", - "op": "add", - "person": { - "email": "foo@zulip.com", - "delivery_email": null, - "user_id": 38, - "avatar_version": 1, - "is_admin": false, - "is_owner": false, - "is_guest": false, - "role": 400, - "is_bot": false, - "full_name": "full name", - "timezone": "", - "is_active": true, - "date_joined": "2020-07-15T15:04:02.030833+00:00", - "avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1", - "profile_data": {} - }, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to guest users when they lose access to a user.\n\n**Changes**: As of Zulip 8.0 (feature level 228), this event is no\nlonger deprecated.\n\nIn Zulip 8.0 (feature level 222), this event was deprecated and no\nlonger sent to clients. Prior to this feature level, it was sent to all\nusers in a Zulip organization when a user was deactivated.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_user"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "person": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of the deactivated user.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the deactivated user.\n" - }, - "full_name": { - "type": "string", - "deprecated": true, - "description": "The full name of the user.\n\n**Deprecated**: We expect to remove this field in the future.\n" - } - } - } - }, - "additionalProperties": false, - "example": { - "type": "realm_user", - "op": "remove", - "person": { - "user_id": 35, - "full_name": "Foo Bot" - }, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to all users in an organization when a user comes back\nonline after being offline for a while.\n\nIn addition to handling these events, a client that wants to\nmaintain presence data must poll the [main presence\nendpoint](https://zulip.com/api/get-presence). Most updates to\npresence data, refreshing the timestamps of users who are already\nonline, do not appear in the event queue. This design is an\noptimization by allowing those updates to be batched up, because\nthere is no urgency in the information that an already-online user\nis still online.\n\nThese events are provided because when a user transitions from\noffline to online, that is information the client may want to show\npromptly in the UI to avoid showing a confusing state (for example,\nif the newly-online user sends a message or otherwise demonstrates\nthey're online).\n\nIf the client supports the `simplified_presence_events` [client\ncapability](/api/register-queue#parameter-client_capabilities),\nthese events will include the `presences` field, which provides the\nmodified user's presence data in the modern format. Clients are\nstrongly encouraged to implement this client capability, as legacy\nformat support will be removed in a future release.\n\nIf the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level\nsetting is set to `true`, then the event is only sent to users\nwho can access the user who came back online.\n\n**Changes**: Prior to Zulip 11.0 (feature level 419), the\n`simplified_presence_events` client capability did not exist.\nTherefore, all events were in the legacy format, and did not\ninclude the `presences` field.\n\nPrior to Zulip 8.0 (feature level 228), this event was sent to all\nusers in the organization.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["presence"] - } - ] - }, - "presences": { - "type": "object", - "description": "Only present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nA dictionary mapping user IDs to the presence data (modern\nformat) for the modified user(s). Clients should support\nupdating multiple users in a single event.\n\n**Changes**: New in Zulip 11.0 (feature level 419).\n", - "additionalProperties": { - "$ref": "#/components/schemas/ModernPresenceFormat" - } - }, - "user_id": { - "type": "integer", - "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe ID of the modified user.\n" - }, - "email": { - "type": "string", - "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe Zulip API email of the user.\n\n**Deprecated**: This field will be removed in a future\nrelease as it is redundant with the `user_id`.\n", - "deprecated": true - }, - "server_timestamp": { - "type": "number", - "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nThe timestamp of when the Zulip server received the user's\npresence as a UNIX timestamp.\n" - }, - "presence": { - "type": "object", - "description": "Not present for clients that support the `simplified_presence_events`\n[client capability](/api/register-queue#parameter-client_capabilities).\n\nObject containing the presence data (legacy format) of of the modified\nuser.\n", - "additionalProperties": { - "type": "object", - "description": "`{client_name}`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `\"website\"` as the server no longer stores which\nclient submitted presence updates.\n\nPreviously, the object key was the client's platform name, for\nexample `website` or `ZulipDesktop`.\n", - "additionalProperties": false, - "properties": { - "client": { - "type": "string", - "description": "The client's platform name.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `\"website\"` as the server no longer stores which\nclient submitted presence updates.\n" - }, - "status": { - "type": "string", - "enum": ["idle", "active"], - "description": "The status of the user on this client. Will be either `idle`\nor `active`.\n" - }, - "timestamp": { - "type": "integer", - "description": "The UNIX timestamp of when this client sent the user's presence\nto the server with the precision of a second.\n" - }, - "pushable": { - "type": "boolean", - "description": "Whether the client is capable of showing mobile/push notifications\nto the user.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this\nwill always be `false` as the server no longer stores which\nclient submitted presence updates.\n" - } - } - } - } - }, - "additionalProperties": false, - "example": { - "type": "presence", - "user_id": 10, - "email": "user10@zulip.testserver", - "server_timestamp": 1594825445.3200784, - "presence": { - "website": { - "client": "website", - "status": "idle", - "timestamp": 1594825445, - "pushable": false - } - }, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent when a new channel is created to users who can see\nthe new channel exists (for private channels, only subscribers and\norganization administrators will receive this event).\n\nThis event is also sent when a user gains access to a channel they\npreviously [could not access](/help/channel-permissions), such as\nwhen their [role](/help/user-roles) changes, a\nprivate channel is made public, or a guest user is subscribed\nto a public (or private) channel.\n\nThis event is also sent when a channel is unarchived but only\nto clients that did not declare the `archived_channels` [client\ncapability][client-capabilities].\n\nNote that organization administrators who are not subscribed will\nnot be able to see content on the channel; just that it exists.\n\n**Changes**: Prior to Zulip 11.0 (feature level 378), this\nevent was sent to all the users who could see the channel when it\nwas unarchived.\n\nPrior to Zulip 8.0 (feature level 220), this event was incorrectly\nnot sent to guest users a web-public channel was created.\n\nPrior to Zulip 8.0 (feature level 205), this event was not sent\nwhen a user gained access to a channel due to their role changing.\n\nPrior to Zulip 8.0 (feature level 192), this event was not sent\nwhen guest users gained access to a public channel by being\nsubscribed.\n\nPrior to Zulip 6.0 (feature level 134), this event was not sent\nwhen a private channel was made public.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["stream"] - } - ] - }, - "op": { - "type": "string", - "enum": ["create"] - }, - "streams": { - "type": "array", - "description": "Array of objects, each containing\ndetails about the newly added channel(s).\n", - "items": { - "$ref": "#/components/schemas/BasicChannel" - } - } - }, - "additionalProperties": false, - "example": { - "type": "stream", - "op": "create", - "streams": [ - { - "name": "private", - "stream_id": 12, - "is_archived": false, - "description": "", - "rendered_description": "", - "date_created": 1691057093, - "creator_id": 11, - "invite_only": true, - "is_web_public": false, - "stream_post_policy": 1, - "history_public_to_subscribers": false, - "first_message_id": null, - "folder_id": 1, - "is_recently_active": true, - "message_retention_days": null, - "is_announcement_only": false, - "can_add_subscribers_group": 2, - "can_remove_subscribers_group": 2, - "can_subscribe_group": 2, - "stream_weekly_traffic": null, - "subscriber_count": 0 - } - ], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent when a user loses access to a channel they previously\n[could access](/help/channel-permissions) because they are\nunsubscribed from a private channel or their [role](/help/user-roles)\nhas changed.\n\nThis event is also sent when a channel is archived but only\nto clients that did not declare the `archived_channels` [client\ncapability][client-capabilities].\n\n**Changes**: Prior to Zulip 11.0 (feature level 378), this\nevent was sent to all the users who could see the channel when it\nwas archived.\n\nPrior to Zulip 8.0 (feature level 205), this event was not sent\nwhen a user lost access to a channel due to their role changing.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["stream"] - } - ] - }, - "op": { - "type": "string", - "enum": ["delete"] - }, - "streams": { - "type": "array", - "deprecated": true, - "description": "Array of objects, each containing ID of the channel that was deleted.\n\n**Changes**: **Deprecated** in Zulip 10.0 (feature level 343)\nand will be removed in a future release. Previously, these\nobjects additionally contained all the standard fields for a\nchannel object.\n", - "items": { - "type": "object", - "properties": { - "stream_id": { - "type": "integer", - "description": "ID of the deleted channel.\n" - } - }, - "additionalProperties": false - } - }, - "stream_ids": { - "type": "array", - "description": "Array containing the IDs of the channels that were deleted.\n\n**Changes**: New in Zulip 10.0 (feature level 343). Previously,\nthese IDs were available only via the legacy `streams` array.\n", - "items": { - "type": "integer" - } - } - }, - "additionalProperties": false, - "example": { - "type": "stream", - "op": "delete", - "streams": [ - { - "stream_id": 1 - }, - { - "stream_id": 2 - } - ], - "stream_ids": [1, 2], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to all users who can see that a channel exists\nwhen a property of that channel changes. See\n[GET /streams](/api/get-streams#response) response\nfor details on the various properties of a channel.\n\nThis event is also sent when archiving or unarchiving a\nchannel to all the users who can see that channel exists\nbut only to the clients that declared the `archived_channels`\n[client capability][client-capabilities].\n\n**Changes**: Prior to Zulip 11.0 (feature level 378),\nthis event was never sent when archiving or unarchiving\na channel.\n\nBefore Zulip 9.0 (feature level 256), this event was never\nsent when the `first_message_id` property of a channel was\nupdated because the oldest message that had been sent to it\nchanged.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["stream"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "stream_id": { - "type": "integer", - "description": "The ID of the channel whose details have changed.\n" - }, - "name": { - "type": "string", - "description": "The name of the channel whose details have changed.\n" - }, - "property": { - "type": "string", - "description": "The property of the channel which has changed. See\n[GET /streams](/api/get-streams#response) response for details\non the various properties of a channel.\n\nClients should handle an \"unknown\" property received here without\ncrashing, since that can happen when connecting to a server running a\nnewer version of Zulip with new features.\n" - }, - "value": { - "description": "The new value of the changed property.\n\n**Changes**: Starting with Zulip 11.0 (feature level 389),\nthis value can be `null` when a channel is removed from the folder.\n\nStarting with Zulip 10.0 (feature level 320), this\nfield can be an object for `can_remove_subscribers_group` property,\nwhich is a [group-setting value][setting-values], when the setting\nis set to a combination of users and groups.\n\n[setting-values]: /api/group-setting-values\n", - "oneOf": [ - { - "type": "object", - "additionalProperties": false, - "properties": { - "direct_members": { - "description": "The list of IDs of individual users in the collection of users with this permission.\n", - "type": "array", - "items": { - "type": "integer" - } - }, - "direct_subgroups": { - "description": "The list of IDs of the groups in the collection of users with this permission.\n", - "type": "array", - "items": { - "type": "integer" - } - } - }, - "description": "If an object, it will be a [group-setting value][setting-values] with these fields:\n\n[setting-values]: /api/group-setting-values\n" - }, - { - "type": "integer" - }, - { - "type": "boolean" - }, - { - "type": "string", - "nullable": true - } - ] - }, - "rendered_description": { - "type": "string", - "description": "Note: Only present if the changed property was `description`.\n\nThe short description of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "history_public_to_subscribers": { - "type": "boolean", - "description": "Note: Only present if the changed property was `invite_only`.\n\nWhether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" - }, - "is_web_public": { - "type": "boolean", - "description": "Note: Only present if the changed property was `invite_only`.\n\nWhether the channel's history is now readable by web-public spectators.\n\n**Changes**: New in Zulip 5.0 (feature level 71).\n" - } - }, - "additionalProperties": false, - "example": { - "op": "update", - "type": "stream", - "property": "invite_only", - "value": true, - "history_public_to_subscribers": true, - "is_web_public": false, - "stream_id": 11, - "name": "test", - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent when a reaction is added to a message.\nSent to all users who were recipients of the message.\n", - "allOf": [ - { - "$ref": "#/components/schemas/EmojiReactionEvent" - }, - { - "additionalProperties": false, - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["reaction"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "message_id": { - "type": "integer", - "description": "The ID of the message to which a reaction was\nadded.\n" - }, - "emoji_code": {}, - "emoji_name": {}, - "reaction_type": {}, - "user_id": {}, - "user": {} - }, - "example": { - "type": "reaction", - "op": "add", - "user_id": 10, - "user": { - "user_id": 10, - "email": "user10@zulip.testserver", - "full_name": "King Hamlet" - }, - "message_id": 32, - "emoji_name": "tada", - "emoji_code": "1f389", - "reaction_type": "unicode_emoji", - "id": 0 - } - } - ] - }, - { - "type": "object", - "description": "Event sent when a reaction is removed from a message.\nSent to all users who were recipients of the message.\n", - "allOf": [ - { - "$ref": "#/components/schemas/EmojiReactionEvent" - }, - { - "additionalProperties": false, - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["reaction"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "message_id": { - "type": "integer", - "description": "The ID of the message from which the reaction was\nremoved.\n" - }, - "emoji_code": {}, - "emoji_name": {}, - "reaction_type": {}, - "user_id": {}, - "user": {} - }, - "example": { - "type": "reaction", - "op": "remove", - "user_id": 10, - "user": { - "user_id": 10, - "email": "user10@zulip.testserver", - "full_name": "King Hamlet" - }, - "message_id": 52, - "emoji_name": "tada", - "emoji_code": "1f389", - "reaction_type": "unicode_emoji", - "id": 0 - } - } - ] - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when the user uploads a new file\nin a Zulip message. Useful to implement live update in UI showing all files\nthe current user has uploaded.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["attachment"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "attachment": { - "$ref": "#/components/schemas/Attachment" - }, - "upload_space_used": { - "type": "integer", - "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" - } - }, - "example": { - "type": "attachment", - "op": "add", - "attachment": { - "id": 1, - "name": "zulip.txt", - "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", - "size": 6, - "create_time": 1594825414000, - "messages": [] - }, - "upload_space_used": 6, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when details of a file that user\nuploaded are changed. Most updates will be changes in the list of\nmessages that reference the uploaded file.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["attachment"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "attachment": { - "$ref": "#/components/schemas/Attachment" - }, - "upload_space_used": { - "type": "integer", - "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" - } - }, - "example": { - "type": "attachment", - "op": "update", - "attachment": { - "id": 1, - "name": "zulip.txt", - "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", - "size": 6, - "create_time": 1594825414000, - "messages": [] - }, - "upload_space_used": 6, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when the user deletes a file\nthey had uploaded. Useful primarily for UI showing all the files\nthe current user has uploaded.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["attachment"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "attachment": { - "type": "object", - "description": "Dictionary containing the ID of the deleted attachment.\n", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "The ID of the deleted attachment.\n" - } - } - }, - "upload_space_used": { - "type": "integer", - "description": "The total size of all files uploaded by in the organization,\nin bytes.\n" - } - }, - "example": { - "type": "attachment", - "op": "remove", - "attachment": { - "id": 1 - }, - "upload_space_used": 0, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when the metadata in the\n`push_devices` dictionary for the user changes.\n\nHelps clients to live-update the `push_devices` dictionary\nreturned in [`POST /register`](/api/register-queue) response.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["push_device"] - } - ] - }, - "push_account_id": { - "type": "string", - "description": "The push account ID for this client registration.\n\nSee [`POST /mobile_push/register`](/api/register-push-device)\nfor details on push account IDs.\n" - }, - "status": { - "type": "string", - "enum": ["active", "failed", "pending"], - "description": "The updated registration status. Will be `\"active\"`, `\"failed\"`, or\n`\"pending\"`.\n" - }, - "error_code": { - "type": "string", - "nullable": true, - "description": "If the status is `\"failed\"`, a [Zulip API error\ncode](/api/rest-error-handling) indicating the type of failure that\noccurred.\n\nThe following error codes have recommended client behavior:\n\n- `\"INVALID_BOUNCER_PUBLIC_KEY\"` - Inform the user to update app.\n- `\"REQUEST_EXPIRED` - Retry with a fresh payload.\n If the status is \"failed\", an error code explaining the failure.\n" - } - }, - "example": { - "id": 1, - "type": "push_device", - "push_account_id": "1234", - "status": "active" - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a submessage is added to a message.\n\nSubmessages are an **experimental** API used for widgets such as the\n`/poll` widget in Zulip.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["submessage"] - } - ] - }, - "msg_type": { - "type": "string", - "description": "The type of the message.\n" - }, - "content": { - "type": "string", - "description": "The new content of the submessage.\n" - }, - "message_id": { - "type": "integer", - "description": "The ID of the message to which the submessage has been added.\n" - }, - "sender_id": { - "type": "integer", - "description": "The ID of the user who sent the message.\n" - }, - "submessage_id": { - "type": "integer", - "description": "The ID of the submessage.\n" - } - }, - "example": { - "type": "submessage", - "msg_type": "widget", - "message_id": 970461, - "submessage_id": 4737, - "sender_id": 58, - "content": "{\"type\":\"vote\",\"key\":\"58,1\",\"vote\":1}", - "id": 28 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users who can access the modified\nuser when the status of a user changes.\n\n**Changes**: Prior to Zulip 8.0 (feature level 228),\nthis event was sent to all users in the organization.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_status"] - } - ] - }, - "away": { - "type": "boolean", - "deprecated": true, - "description": "Whether the user has marked themself \"away\" with this status.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n" - }, - "status_text": { - "type": "string", - "description": "The text content of the status message.\n\nThis will be `\"\"` for users who set a status without selecting\nor writing a message.\n" - }, - "emoji_name": { - "type": "string", - "description": "The [emoji name](/api/update-status#parameter-emoji_name) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - }, - "emoji_code": { - "type": "string", - "description": "The [emoji code](/api/update-status#parameter-emoji_code) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - }, - "reaction_type": { - "type": "string", - "enum": [ - "unicode_emoji", - "realm_emoji", - "zulip_extra_emoji" - ], - "description": "The [emoji type](/api/update-status#parameter-reaction_type) for\nthe emoji the user selected for their new status.\n\nThis will be `\"\"` for users who set a status without selecting\nan emoji.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - }, - "user_id": { - "type": "integer", - "description": "The ID of the user whose status changed.\n" - } - }, - "example": { - "type": "user_status", - "user_id": 10, - "away": true, - "status_text": "out to lunch", - "emoji_name": "car", - "emoji_code": "1f697", - "reaction_type": "unicode_emoji", - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when new custom\nprofile field types are configured for that Zulip organization.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["custom_profile_fields"] - } - ] - }, - "fields": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains\ndetails of a single new custom profile field for the Zulip\norganization.\n", - "items": { - "$ref": "#/components/schemas/CustomProfileField" - } - } - }, - "example": { - "type": "custom_profile_fields", - "fields": [ - { - "id": 1, - "name": "Phone number", - "type": 1, - "hint": "", - "field_data": "", - "order": 1, - "required": true, - "editable_by_user": true - }, - { - "id": 2, - "name": "Biography", - "type": 2, - "hint": "What are you known for?", - "field_data": "", - "order": 2, - "required": true, - "editable_by_user": true - }, - { - "id": 3, - "name": "Favorite food", - "type": 1, - "hint": "Or drink, if you'd prefer", - "field_data": "", - "order": 3, - "required": false, - "editable_by_user": true - }, - { - "id": 4, - "name": "Favorite editor", - "type": 3, - "hint": "", - "field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}", - "order": 4, - "display_in_profile_summary": true, - "required": true, - "editable_by_user": true - }, - { - "id": 5, - "name": "Birthday", - "type": 4, - "hint": "", - "field_data": "", - "order": 5, - "required": false, - "editable_by_user": false - }, - { - "id": 6, - "name": "Favorite website", - "type": 5, - "hint": "Or your personal blog's URL", - "field_data": "", - "order": 6, - "display_in_profile_summary": true, - "required": false, - "editable_by_user": true - }, - { - "id": 7, - "name": "Mentor", - "type": 6, - "hint": "", - "field_data": "", - "order": 7, - "required": true, - "editable_by_user": false - }, - { - "id": 8, - "name": "GitHub", - "type": 7, - "hint": "Enter your GitHub username", - "field_data": "{\"subtype\":\"github\"}", - "order": 8, - "required": true, - "editable_by_user": true - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when an organization\nadministrator changes the organization's configured default channel groups.\n\nDefault channel groups are an **experimental** feature that is not yet\nstabilized.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["default_stream_groups"] - } - ] - }, - "default_stream_groups": { - "type": "array", - "description": "An array of dictionaries where each dictionary\ncontains details about a single default channel group.\n", - "items": { - "$ref": "#/components/schemas/DefaultChannelGroup" - } - } - }, - "example": { - "type": "default_stream_groups", - "default_stream_groups": [ - { - "name": "group1", - "id": 2, - "description": "New description", - "streams": [3, 1, 5] - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the\ndefault channels in the organization are changed by an\norganization administrator.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["default_streams"] - } - ] - }, - "default_streams": { - "type": "array", - "description": "An array of IDs of all the [default channels](/help/set-default-streams-for-new-users)\nin the organization.\n\n**Changes**: Before Zulip 10.0 (feature level 330),\nwe sent array of dictionaries where each dictionary\ncontained details about a single default stream for\nthe Zulip organization.\n", - "items": { - "type": "integer" - } - } - }, - "example": { - "type": "default_streams", - "default_streams": [2, 3], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a message has been deleted.\n\nSent to all users who currently are subscribed to the\nmessages' recipient. May also be sent to additional users\nwho had access to it, including, in particular, an\nadministrator user deleting messages in a stream that they\nare not subscribed to.\n\nThis means that clients can assume that they will always\nreceive an event of this type for deletions that the\nclient itself initiated.\n\nThis event is also sent when the user loses access to a message,\nsuch as when it is [moved to a channel][message-move-channel] that\nthe user does not [have permission to access][channel-access].\n\n**Changes**: Before Zulip 9.0 (feature level 274), this\nevent was only sent to subscribers of the message's recipient.\n\nBefore Zulip 5.0 (feature level 77), events\nfor direct messages contained additional `sender_id` and\n`recipient_id` fields.\n\n[message-move-channel]: /help/move-content-to-another-channel\n[channel-access]: /help/channel-permissions\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["delete_message"] - } - ] - }, - "message_ids": { - "type": "array", - "description": "Only present for clients that support the `bulk_message_deletion`\n[client capability][client-capabilities].\n\nA sorted list containing the IDs of the newly deleted messages.\n\n**Changes**: Before Zulip 11.0 (feature level 393), this list was\nnot guaranteed to be sorted.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", - "items": { - "type": "integer" - } - }, - "message_id": { - "type": "integer", - "description": "Only present for clients that do not support the `bulk_message_deletion`\n[client capability][client-capabilities].\n\nThe ID of the newly deleted message.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "message_type": { - "type": "string", - "description": "The type of message. Either `\"stream\"` or `\"private\"`.\n", - "enum": ["private", "stream"] - }, - "stream_id": { - "type": "integer", - "description": "Only present if `message_type` is `\"stream\"`.\n\nThe ID of the channel to which the message was sent.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `message_type` is `\"stream\"`.\n\nThe topic to which the message was sent.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name was empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - } - }, - "example": { - "type": "delete_message", - "message_type": "private", - "message_id": 37, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user's set of\nconfigured muted topics have changed.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["muted_topics"] - } - ] - }, - "muted_topics": { - "type": "array", - "deprecated": true, - "description": "Array of tuples, where each tuple describes a muted topic.\nThe first element of the tuple is the channel name in which the topic\nhas to be muted, the second element is the topic name to be muted\nand the third element is an integer UNIX timestamp representing\nwhen the topic was muted.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level\n134). Starting with this version, clients that explicitly\nrequested the replacement `user_topic` event type when\nregistering their event queue will not receive this legacy\nevent type.\n\nBefore Zulip 3.0 (feature level 1), the `muted_topics`\narray objects were 2-item tuples and did not include the timestamp\ninformation for when the topic was muted.\n", - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ] - } - } - } - }, - "additionalProperties": false, - "example": { - "type": "muted_topics", - "muted_topics": [ - ["Denmark", "topic", 1594825442] - ], - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when the user mutes/unmutes\na topic, or otherwise modifies their personal per-topic\nconfiguration.\n\n**Changes**: New in Zulip 6.0 (feature level 134). Previously,\nclients were notified about changes in muted topic\nconfiguration via the `muted_topics` event type.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_topic"] - } - ] - }, - "stream_id": { - "type": "integer", - "description": "The ID of the channel to which the topic belongs.\n" - }, - "topic_name": { - "type": "string", - "description": "The name of the topic.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "last_updated": { - "type": "integer", - "description": "An integer UNIX timestamp representing when the user-topic\nrelationship was last changed.\n" - }, - "visibility_policy": { - "type": "integer", - "description": "An integer indicating the user's visibility\npreferences for the topic, such as whether the topic\nis muted.\n\n- 0 = None. Used to indicate that the user no\n longer has a special visibility policy for this topic.\n- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).\n- 2 = Unmuted. Used to record unmuted topics.\n- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n\nIn Zulip 7.0 (feature level 170), added unmuted as a visibility\npolicy option.\n" - } - }, - "additionalProperties": false, - "example": { - "id": 1, - "type": "user_topic", - "stream_id": 1, - "topic_name": "topic", - "last_updated": 1594825442, - "visibility_policy": 1 - } - }, - { - "type": "object", - "description": "Event sent to a user's clients when that user's set of\nconfigured [muted users](/api/mute-user) have changed.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["muted_users"] - } - ] - }, - "muted_users": { - "type": "array", - "description": "A list of dictionaries where each dictionary describes\na muted user.\n", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the user ID and timestamp of a muted user.\n", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the muted user.\n" - }, - "timestamp": { - "type": "integer", - "description": "An integer UNIX timestamp representing when the user was muted.\n" - } - } - } - } - }, - "additionalProperties": false, - "example": { - "type": "muted_users", - "muted_users": [ - { - "id": 1, - "timestamp": 1594825442 - }, - { - "id": 22, - "timestamp": 1654865392 - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Heartbeat events are sent by the server to avoid\nlongpolling connections being affected by networks that\nkill idle HTTP connections.\n\nClients do not need to do anything to process these\nevents, beyond the common `last_event_id` accounting.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["heartbeat"] - } - ] - } - }, - "example": { - "type": "heartbeat", - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when the set of onboarding steps to show for the current user\nhas changed (e.g. because the user dismissed one).\n\nClients that feature a similar tutorial experience to the Zulip web app\nmay want to handle these events.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this event was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["onboarding_steps"] - } - ] - }, - "onboarding_steps": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains details about a\nsingle onboarding step.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this array was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported, and the `type` field in these objects did not\nexist as all onboarding steps were implicitly hotspots.\n", - "items": { - "$ref": "#/components/schemas/OnboardingStep" - } - } - }, - "example": { - "type": "onboarding_steps", - "onboarding_steps": [ - { - "type": "one_time_notice", - "name": "visibility_policy_banner" - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a message's content, topic and/or\nchannel has been edited or when a message's content\nhas a rendering update, such as for an\n[inline URL preview][inline-url-previews].\nSent to all users who had received the original\nmessage.\n\n[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews\n\n**Changes**: In Zulip 10.0 (feature level 284), removed the\n`prev_rendered_content_version` field as it is an internal\nserver implementation detail not used by any client.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["update_message"] - } - ] - }, - "user_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who sent the message.\n\nWill be `null` when event is for a rendering update of the original\nmessage, such as for an [inline URL preview][inline-url-previews].\n\n**Changes**: Prior to Zulip 5.0 (feature level 114), this field was\nomitted for [inline URL preview][inline-url-previews] updates.\n" - }, - "rendering_only": { - "type": "boolean", - "description": "Whether the event only updates the rendered content of the message.\n\nThis field should be used by clients to determine if the event\nonly provides a rendering update to the message content,\nsuch as for an [inline URL preview][inline-url-previews].\nWhen `true`, the event does not reflect a user-generated edit\nand does not modify the message history.\n\n**Changes**: New in Zulip 5.0 (feature level 114). Clients can\ncorrectly identify these rendering update events prior to this\nfeature level by checking whether the `user_id` field was omitted.\n" - }, - "message_id": { - "type": "integer", - "description": "The ID of the message which was edited or updated.\n\nThis field should be used to apply content edits to the client's\ncached message history, or to apply rendered content updates.\n\nIf the channel or topic was changed, the set of moved messages is\nencoded in the separate `message_ids` field, which is guaranteed\nto include `message_id`.\n" - }, - "message_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A sorted list of IDs of messages to which any channel or topic\nchanges encoded in this event should be applied.\n\nThis list always includes `message_id`, even when there are no\nchannel or topic changes to apply.\n\nThese messages are guaranteed to have all been previously sent\nto channel `stream_id` with topic `orig_subject`, and have been\nmoved to `new_stream_id` with topic `subject` (if those fields\nare present in the event).\n\nClients processing these events should update all cached message\nhistory associated with the moved messages (including adjusting\n`unread_msgs` data structures, where the client may not have the\nmessage itself in its history) to reflect the new channel and\ntopic.\n\nContent changes should be applied only to the single message\nindicated by `message_id`.\n\n**Changes**: Before Zulip 11.0 (feature level 393), this list\nwas not guaranteed to be sorted.\n" - }, - "flags": { - "type": "array", - "description": "The user's personal [message flags][message-flags] for the\nmessage with ID `message_id` following the edit.\n\nA client application should compare these to the original flags\nto identify cases where a mention or alert word was added by the\nedit.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", - "items": { - "type": "string" - } - }, - "edit_timestamp": { - "type": "integer", - "description": "The UNIX timestamp when this message edit operation was processed by\nthe server, in UTC seconds.\n\n**Changes**: Prior to Zulip 5.0 (feature level 114), this field\nwas omitted for [inline URL preview][inline-url-previews] updates.\n" - }, - "stream_name": { - "type": "string", - "description": "Only present if the message was edited and originally sent to a channel.\n\nThe name of the channel that the message was sent to. Clients\nare recommended to use the `stream_id` field instead.\n" - }, - "stream_id": { - "type": "integer", - "description": "Only present if the message was edited and originally sent to a channel.\n\nThe pre-edit channel for all of the messages with IDs in\n`message_ids`.\n\n**Changes**: As of Zulip 5.0 (feature level 112), this field\nis present for all edits to a channel message. Previously, it\nwas not present when only the content of the channel message was\nedited.\n" - }, - "new_stream_id": { - "type": "integer", - "description": "Only present if message(s) were moved to a different channel.\n\nThe post-edit channel for all of the messages with IDs in\n`message_ids`.\n" - }, - "propagate_mode": { - "type": "string", - "description": "Only present if this event moved messages to a different\ntopic and/or channel.\n\nThe choice the editing user made about which messages should be\naffected by a channel/topic edit:\n\n- `\"change_one\"`: Just change the one indicated in `message_id`.\n- `\"change_later\"`: Change messages in the same topic that had\n been sent after this one.\n- `\"change_all\"`: Change all messages in that topic.\n\nThis parameter should be used to decide whether to change\nnavigation and compose box state in response to the edit. For\nexample, if the user was previously in topic narrow, and the\ntopic was edited with `\"change_later\"` or `\"change_all\"`, the Zulip\nweb app will automatically navigate to the new topic narrow.\nSimilarly, a message being composed to the old topic should\nhave its recipient changed to the new topic.\n\nThis navigation makes it much more convenient to move content\nbetween topics without disruption or messages continuing\nto be sent to the pre-edit topic by accident.\n", - "enum": [ - "change_one", - "change_later", - "change_all" - ] - }, - "orig_subject": { - "type": "string", - "description": "Only present if this event moved messages to a different\ntopic and/or channel.\n\nThe pre-edit topic for all of the messages with IDs in\n`message_ids`.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual pre-edit topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "subject": { - "type": "string", - "description": "Only present if this event moved messages to a different topic;\nthis field will not be present when moving messages to the same\ntopic name in a different channel.\n\nThe post-edit topic for all of the messages with IDs in\n`message_ids`.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual post-edit topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "topic_links": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "text": { - "type": "string", - "description": "The original link text present in the topic.\n" - }, - "url": { - "type": "string", - "description": "The expanded target url which the link points to.\n" - } - } - }, - "description": "Only present if this event moved messages to a different topic;\nthis field will not be present when moving messages to the same\ntopic name in a different channel.\n\nData on any links to be included in the `topic`\nline (these are generated by\n[custom linkification filter](/help/add-a-custom-linkifier)\nthat match content in the message's topic.), corresponding\nto the post-edit topic.\n\n**Changes**: This field contained a list of urls before\nZulip 4.0 (feature level 46).\n\nNew in Zulip 3.0 (feature level 1). Previously, this field\nwas called `subject_links`; clients are recommended to\nrename `subject_links` to `topic_links` if present for\ncompatibility with older Zulip servers.\n" - }, - "orig_content": { - "type": "string", - "description": "Only present if this event changed the message content.\n\nThe original content of the message with ID `message_id`\nimmediately prior to this edit, in the original [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n" - }, - "orig_rendered_content": { - "type": "string", - "description": "Only present if this event changed the message content.\n\nThe original content of the message with ID `message_id`\nimmediately prior to this edit, rendered as HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "content": { - "type": "string", - "description": "Only present if this event changed the message content or\nupdated the message content for an\n[inline URL preview][inline-url-previews].\n\nThe new content of the message with ID `message_id`, in the\noriginal [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n" - }, - "rendered_content": { - "type": "string", - "description": "Only present if this event changed the message content or\nupdated the message content for an\n[inline URL preview][inline-url-previews].\n\nThe new content of the message with ID `message_id`,\nrendered in HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "is_me_message": { - "type": "boolean", - "description": "Only present if this event changed the message content.\n\nWhether the message with ID `message_id` is now a\n[/me status message][status-messages].\n\n[status-messages]: /help/format-your-message-using-markdown#status-messages\n" - } - }, - "required": [ - "type", - "id", - "user_id", - "message_id", - "message_ids", - "flags", - "edit_timestamp", - "rendering_only" - ], - "example": { - "type": "update_message", - "user_id": 10, - "edit_timestamp": 1594825451, - "message_id": 58, - "stream_name": "Verona", - "orig_content": "hello", - "orig_rendered_content": "

hello

", - "content": "new content", - "rendered_content": "

new content

", - "is_me_message": false, - "propagate_mode": "change_all", - "stream_id": 5, - "orig_subject": "test", - "subject": "new_topic", - "topic_links": [], - "message_ids": [57, 58], - "flags": [], - "rendering_only": false, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a user starts typing a message.\n\nSent to all clients for users who would receive the\nmessage being typed, with the additional rule that typing\nnotifications for channel messages are only sent to clients\nthat included `stream_typing_notifications` in their\n[client capabilities][client-capabilities] when registering\nthe event queue.\n\nSee [POST /typing](/api/set-typing-status) endpoint for more details.\n\n**Changes**: Typing notifications for channel messages are new in\nZulip 4.0 (feature level 58).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["typing"] - } - ] - }, - "op": { - "type": "string", - "enum": ["start"] - }, - "message_type": { - "type": "string", - "description": "Type of message being composed. Must be `\"stream\"` or `\"direct\"`.\n\n**Changes**: In Zulip 8.0 (feature level 215), replaced the\nvalue `\"private\"` with `\"direct\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously, all typing\nnotifications were implicitly direct messages.\n", - "enum": ["direct", "stream"] - }, - "sender": { - "additionalProperties": false, - "type": "object", - "description": "Object describing the user who is typing the message.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The user's ID.\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email address for the user.\n" - } - } - }, - "recipients": { - "type": "array", - "description": "Only present if `message_type` is `\"direct\"`.\n\nArray of dictionaries describing the set of users who would be\nrecipients of the message being typed. Each dictionary contains\ndetails about one of the recipients. The sending user is guaranteed\nto appear among the recipients.\n", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the user ID and Zulip API email of a recipient.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user.\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email address for the user.\n" - } - } - } - }, - "stream_id": { - "type": "integer", - "description": "Only present if `message_type` is `\"stream\"`.\n\nThe unique ID of the channel to which message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `message_type` is `\"stream\"`.\n\nTopic within the channel where the message is being typed.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - } - }, - "example": { - "type": "typing", - "op": "start", - "message_type": "direct", - "sender": { - "user_id": 10, - "email": "user10@zulip.testserver" - }, - "recipients": [ - { - "user_id": 8, - "email": "user8@zulip.testserver" - }, - { - "user_id": 10, - "email": "user10@zulip.testserver" - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a user stops typing a message.\n\nSent to all clients for users who would receive the message\nthat was previously being typed, with the additional rule\nthat typing notifications for channel messages are only sent to\nclients that included `stream_typing_notifications` in their\n[client capabilities][client-capabilities] when registering\nthe event queue.\n\nSee [POST /typing](/api/set-typing-status) endpoint for more details.\n\n**Changes**: Typing notifications for channel messages are new in\nZulip 4.0 (feature level 58).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["typing"] - } - ] - }, - "op": { - "type": "string", - "enum": ["stop"] - }, - "message_type": { - "type": "string", - "description": "Type of message being composed. Must be `\"stream\"` or `\"direct\"`.\n\n**Changes**: In Zulip 8.0 (feature level 215), replaced the\nvalue `\"private\"` with `\"direct\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously all typing\nnotifications were implicitly direct messages.\n", - "enum": ["direct", "stream"] - }, - "sender": { - "additionalProperties": false, - "type": "object", - "description": "Object describing the user who was previously typing the message.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The user's ID.\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email address for the user.\n" - } - } - }, - "recipients": { - "type": "array", - "description": "Only present if `message_type` is `\"direct\"`.\n\nArray of dictionaries describing the set of users who would be\nrecipients of the message that was previously being typed. Each\ndictionary contains details about one of the recipients. The\nsending user is guaranteed to appear among the recipients.\n", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the user ID and email of a recipient.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user.\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email address for the user.\n" - } - } - } - }, - "stream_id": { - "type": "integer", - "description": "Only present if `message_type` is `\"stream\"`.\n\nThe unique ID of the channel to which message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `message_type` is `\"stream\"`.\n\nTopic within the channel where the message is being typed.\n\n**Changes**: New in Zulip 4.0 (feature level 58). Previously,\ntyping notifications were only for direct messages.\n" - } - }, - "example": { - "type": "typing", - "op": "stop", - "message_type": "direct", - "sender": { - "user_id": 10, - "email": "user10@zulip.testserver" - }, - "recipients": [ - { - "user_id": 8, - "email": "user8@zulip.testserver" - }, - { - "user_id": 10, - "email": "user10@zulip.testserver" - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a user starts editing a message.\nEvent sent when a user starts typing in a textarea to edit the\ncontent of a message. See the [edit message typing notifications\nendpoint](/api/set-typing-status-for-message-edit).\n\nClients requesting `typing_edit_message` event type that have\n`receives_typing_notifications` enabled will receive this event if\nthey would have been notified if the message's content edit were to\nbe saved (E.g., because they were a direct message recipient or\nare a subscribe to the channel).\n\n**Changes**: New in Zulip 10.0 (feature level 351). Previously,\ntyping notifications were not available when editing messages.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["typing_edit_message"] - } - ] - }, - "op": { - "type": "string", - "enum": ["start"] - }, - "sender_id": { - "type": "integer", - "description": "The ID of the user who is typing the edit of the\nmessage.\n\nClients should be careful to display this user as the person who\nis typing, not that of the sender of the message, in case a\ncollaborative editing feature be might be added in the future.\n" - }, - "message_id": { - "type": "integer", - "description": "Indicates the message id of the message that is being edited.\n" - }, - "recipient": { - "type": "object", - "description": "Object containing details about recipients of message edit typing notification.\n", - "additionalProperties": false, - "properties": { - "type": { - "type": "string", - "description": "Type of message being composed. Must be `\"channel\"` or `\"direct\"`.\n", - "enum": ["direct", "channel"] - }, - "channel_id": { - "type": "integer", - "description": "Only present if `type` is `\"channel\"`.\n\nThe unique ID of the channel to which message is being edited.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `type` is `\"channel\"`.\n\nTopic within the channel where the message is being edited.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Present only if `type` is `direct`.\n\nThe user IDs of every recipient of this direct message.\n" - } - } - } - }, - "example": { - "type": "typing_edit_message", - "op": "start", - "sender_id": 10, - "recipient": { - "type": "direct", - "user_ids": [8, 10] - }, - "message_id": 7, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a user stops typing in a textarea to edit the\ncontent of a message. See the [edit message typing notifications\nendpoint](/api/set-typing-status-for-message-edit).\n\nClients requesting `typing_edit_message` event type that have\n`receives_typing_notifications` enabled will receive this event if\nthey would have been notified if the message's content edit were to\nbe saved (E.g., because they were a direct message recipient or\nare a subscribe to the channel).\n\n**Changes**: New in Zulip 10.0 (feature level 351). Previously,\ntyping notifications were not available when editing messages.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["typing_edit_message"] - } - ] - }, - "op": { - "type": "string", - "enum": ["stop"] - }, - "sender_id": { - "type": "integer", - "description": "The ID of the user who sent the message.\n" - }, - "message_id": { - "type": "integer", - "description": "Indicates the message id of the message that is being edited.\n" - }, - "recipient": { - "type": "object", - "description": "Object containing details about recipients of message edit typing notification.\n", - "additionalProperties": false, - "properties": { - "type": { - "type": "string", - "description": "Type of message being composed. Must be `\"channel\"` or `\"direct\"`.\n", - "enum": ["direct", "channel"] - }, - "channel_id": { - "type": "integer", - "description": "Only present if `type` is `\"channel\"`.\n\nThe unique ID of the channel to which message is being edited.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `type` is `\"channel\"`.\n\nTopic within the channel where the message is being edited.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Present only if `type` is `direct`.\n\nThe user IDs of every recipient of this direct message.\n" - } - } - } - }, - "example": { - "type": "typing_edit_message", - "op": "stop", - "sender_id": 10, - "message_id": 31, - "recipient": { - "type": "direct", - "user_ids": [8, 10] - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user when [message flags][message-flags] are added\nto messages.\n\nThis can reflect a direct user action, or can be the indirect\nconsequence of another action. Whatever the cause, if there's a change\nin the set of message flags that the user has for a message, then an\n`update_message_flags` event will be sent with the change. Note\nthat this applies when the user already had access to the message, and\ncontinues to have access to it. When a message newly appears or\ndisappears, a [`message`][message-event] or\n[`delete_message`][message-delete] event is sent instead.\n\nSome examples of actions that trigger an `update_message_flags`\nevent:\n\n- The `\"starred\"` flag is added when the user chooses to [star a\n message](/help/star-a-message).\n- The `\"read\"` flag is added when the user marks messages as read by\n scrolling through them, or uses [Mark all messages as read][all-read]\n on a conversation.\n- The `\"read\"` flag is added when the user [mutes](/help/mute-a-user) a\n message's sender.\n- The `\"read\"` flag is added after the user unsubscribes from a channel,\n or messages are moved to a not-subscribed channel, provided the user\n can still access the messages at all. Note a\n [`delete_message`][message-delete] event is sent in the case where the\n user can no longer access the messages.\n\nIn some cases, a change in message flags that's caused by another change\nmay happen a short while after the original change, rather than\nsimultaneously. For example, when messages that were unread are moved to\na channel where the user is not subscribed, the resulting change in\nmessage flags (and the corresponding `update_message_flags` event with\nflag `\"read\"`) may happen later than the message move itself. The delay\nin that example is typically at most a few hundred milliseconds and can\nin rare cases be minutes or longer.\n\n[message-flags]: /api/update-message-flags#available-flags\n[message-event]: /api/get-events#message\n[message-delete]: /api/get-events#delete_message\n[all-read]: /help/marking-messages-as-read#mark-messages-in-multiple-topics-and-channels-as-read\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["update_message_flags"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "operation": { - "deprecated": true, - "description": "Old name for the `op` field in this event type.\n\n**Deprecated** in Zulip 4.0 (feature level 32), and\nreplaced by the `op` field.\n", - "type": "string", - "enum": ["add"] - }, - "flag": { - "type": "string", - "description": "The [flag][message-flags] that was added.\n" - }, - "messages": { - "type": "array", - "description": "Array containing the IDs of all messages to which\nthe flag was added.\n", - "items": { - "type": "integer" - } - }, - "all": { - "type": "boolean", - "description": "Whether the specified flag was added to all messages.\nThis field is only relevant for the `\"read\"` flag, and\nwill be `false` for all other flags.\n\nWhen `true` for the `\"read\"` flag, then the `messages`\narray will be empty.\n" - } - }, - "example": { - "type": "update_message_flags", - "op": "add", - "operation": "add", - "flag": "starred", - "messages": [63], - "all": false, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user when [message flags][message-flags] are\nremoved from messages.\n\nSee the description for the [`update_message_flags` op:\n`add`](/api/get-events#update_message_flags-add) event for\nmore details about these events.\n\n[message-flags]: /api/update-message-flags#available-flags\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["update_message_flags"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "operation": { - "deprecated": true, - "type": "string", - "description": "Old name for the `op` field in this event type.\n\n**Deprecated** in Zulip 4.0 (feature level 32), and\nreplaced by the `op` field.\n", - "enum": ["remove"] - }, - "flag": { - "type": "string", - "description": "The [flag][message-flags] to be removed.\n" - }, - "messages": { - "type": "array", - "description": "Array containing the IDs of the messages from which the flag\nwas removed.\n", - "items": { - "type": "integer" - } - }, - "all": { - "deprecated": true, - "type": "boolean", - "description": "Will be `false` for all specified flags.\n\n**Deprecated** and will be removed in a future release.\n" - }, - "message_details": { - "description": "Only present if the specified `flag` is `\"read\"`.\n\nA set of data structures describing the messages that\nare being marked as unread with additional details to\nallow clients to update the `unread_msgs` data\nstructure for these messages (which may not be\notherwise known to the client).\n\n**Changes**: New in Zulip 5.0 (feature level 121). Previously,\nmarking already read messages as unread was not\nsupported by the Zulip API.\n", - "type": "object", - "additionalProperties": { - "type": "object", - "description": "`{message_id}`: Object containing details about the\nmessage with the specified ID.\n", - "additionalProperties": false, - "required": ["type"], - "properties": { - "type": { - "type": "string", - "description": "The type of this message. Either `\"stream\"` or `\"private\"`.\n", - "enum": ["private", "stream"] - }, - "mentioned": { - "type": "boolean", - "description": "A flag which indicates whether the message contains a mention\nof the user.\n\nPresent only if the message mentions the current user.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Present only if `type` is `private`.\n\nThe user IDs of every recipient of this direct message, excluding yourself.\nWill be the empty list for a message you had sent to only yourself.\n" - }, - "stream_id": { - "type": "integer", - "description": "Present only if `type` is `\"stream\"`.\n\nThe ID of the channel where the message was sent.\n" - }, - "topic": { - "type": "string", - "description": "Present only if `type` is `\"stream\"`.\n\nName of the topic where the message was sent.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nif the actual topic name is empty string, this field's value will instead\nbe the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response.\n\n**Changes**: Before 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "unmuted_stream_msg": { - "type": "boolean", - "deprecated": true, - "description": "**Deprecated** internal implementation detail. Clients should\nignore this field as it will be removed in the future.\n" - } - } - } - } - }, - "example": { - "type": "update_message_flags", - "op": "remove", - "operation": "remove", - "flag": "starred", - "messages": [63], - "message_details": { - "63": { - "type": "stream", - "stream_id": 22, - "topic": "lunch" - } - }, - "all": false, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to users in an organization when a [user group](/help/user-groups) is created.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "group": { - "$ref": "#/components/schemas/UserGroup" - } - }, - "example": { - "type": "user_group", - "op": "add", - "group": { - "name": "backend", - "members": [12], - "creator_id": 9, - "date_created": 1717484476, - "description": "Backend team", - "id": 2, - "is_system_group": false, - "can_add_members_group": 16, - "can_join_group": 16, - "can_leave_group": 15, - "can_manage_group": 16, - "can_mention_group": 11, - "can_remove_members_group": 16 - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization\nwhen a property of a user group is changed.\n\nFor group deactivation, this event is only sent\nif `include_deactivated_groups` client capability\nis set to `true`.\n\nThis event is also sent when deactivating or reactivating\na user for settings set to anonymous user groups which the\nuser is direct member of. When deactivating the user, event\nis only sent to users who cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when deactivating or reactivating a user.\n\nPrior to Zulip 10.0 (feature level 294), this event was sent to\nall clients when a user group was deactivated.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the user group whose details have changed.\n" - }, - "data": { - "type": "object", - "additionalProperties": false, - "description": "Dictionary containing the changed details of the user group.\n", - "properties": { - "name": { - "type": "string", - "description": "The new name of the user group. Only present if the group's name changed.\n" - }, - "description": { - "type": "string", - "description": "The new description of the group. Only present if the description\nchanged.\n" - }, - "can_add_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this group. Only present if this user\ngroup permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_join_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this group. Only present if this user group\npermission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_leave_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this group. Only present if this user group\npermission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_manage_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this group][manage-user-groups]. Only present\nif this user group permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" - } - ] - }, - "can_mention_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions]. Only present\nif this user group permission setting changed.\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" - } - ] - }, - "can_remove_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this group. Only present if this\nuser group permission setting changed.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "deactivated": { - "type": "boolean", - "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" - } - } - } - }, - "example": { - "type": "user_group", - "op": "update", - "group_id": 2, - "data": { - "description": "Mention this group to get the security team's attention." - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when users have been added to a user group.\n\nThis event is also sent when reactivating a user for all the user\ngroups the reactivated user was a member of before being deactivated.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when reactivating a user.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add_members"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the user group with new members.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the IDs of the users who have been added\nto the user group.\n" - } - }, - "example": { - "type": "user_group", - "op": "add_members", - "group_id": 2, - "user_ids": [10], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when users have been removed from\na user group.\n\nThis event is also sent when deactivating a user, for all\nthe user groups the deactivated user is a member of, but only\nto the users who cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303),\nthis event can also be sent when deactivating a user.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove_members"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the user group whose details have changed.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the IDs of the users who have been removed\nfrom the user group.\n" - } - }, - "example": { - "type": "user_group", - "op": "remove_members", - "group_id": 2, - "user_ids": [10], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when subgroups have been added to\na user group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add_subgroups"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the user group whose details have changed.\n" - }, - "direct_subgroup_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the IDs of the subgroups that have been added\nto the user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nPreviously, this was called `subgroup_ids`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" - } - }, - "example": { - "type": "user_group", - "op": "add_subgroups", - "group_id": 2, - "direct_subgroup_ids": [10], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when subgroups have been removed from\na user group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove_subgroups"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the user group whose details have changed.\n" - }, - "direct_subgroup_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the IDs of the subgroups that have been\nremoved from the user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nPreviously, this was called `subgroup_ids`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" - } - }, - "example": { - "type": "user_group", - "op": "remove_subgroups", - "group_id": 2, - "direct_subgroup_ids": [10], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent when a user group is deactivated but only to clients\nwith `include_deactivated_groups` client capability set to `false`.\n\n**Changes**: Prior to Zulip 10.0 (feature level 294), this\nevent was sent when a user group was deleted.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["user_group"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "group_id": { - "type": "integer", - "description": "The ID of the group which has been deleted.\n" - } - }, - "example": { - "type": "user_group", - "op": "remove", - "group_id": 2, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the\nset of configured [linkifiers](/help/add-a-custom-linkifier)\nfor the organization has changed.\n\nProcessing this event is important for doing Markdown local echo\ncorrectly.\n\nClients will not receive this event unless the event queue is\nregistered with the client capability\n`{\"linkifier_url_template\": true}`.\nSee [`POST /register`](/api/register-queue#parameter-client_capabilities)\nfor how client capabilities can be specified.\n\n**Changes**: Before Zulip 7.0 (feature level 176), the\n`linkifier_url_template` client capability was not required. The\nrequirement was added because linkifiers were updated to contain\na URL template instead of a URL format string, which was not a\nbackwards-compatible change.\n\nNew in Zulip 4.0 (feature level 54), replacing the deprecated\n`realm_filters` event type.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_linkifiers"] - } - ] - }, - "realm_linkifiers": { - "type": "array", - "description": "An ordered array of dictionaries where each dictionary contains\ndetails about a single linkifier.\n\nClients should always process linkifiers in the order given;\nthis is important if the realm has linkifiers with overlapping\npatterns. The order can be modified using [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "pattern": { - "type": "string", - "description": "The [Python regular expression](https://docs.python.org/3/howto/regex.html)\nthat represents the pattern that should be linkified by this linkifier.\n" - }, - "url_template": { - "type": "string", - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant\nURL template to be used for linkifying matches.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the linkifier.\n" - } - } - } - } - }, - "example": { - "type": "realm_linkifiers", - "realm_linkifiers": [ - { - "pattern": "#(?P[123])", - "url_template": "https://realm.com/my_realm_filter/{id}", - "id": 1 - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "deprecated": true, - "description": "Legacy event type that is no longer sent to clients. Previously, sent\nto all users in a Zulip organization when the set of configured\n[linkifiers](/help/add-a-custom-linkifier) for the organization was\nchanged.\n\n**Changes**: Prior to Zulip 7.0 (feature level 176), this event type\nwas sent to clients.\n\n**Deprecated** in Zulip 4.0 (feature level 54), and replaced by the\n`realm_linkifiers` event type, which has a clearer name and format.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_filters"] - } - ] - }, - "realm_filters": { - "type": "array", - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "integer" - }, - { - "type": "string" - } - ] - } - }, - "description": "An array of tuples, where each tuple described a linkifier. The first\nelement of the tuple was a string regex pattern which represented the\npattern to be linkified on matching, for example `\"#(?P[123])\"`.\nThe second element was the URL format string that the pattern should be\nlinkified with. A URL format string for the above example would be\n`\"https://realm.com/my_realm_filter/%(id)s\"`. And the third element\nwas the ID of the realm filter.\n" - } - }, - "example": { - "type": "realm_filters", - "realm_filters": [], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the\nset of configured [code playgrounds](/help/code-blocks#code-playgrounds)\nfor the organization has changed.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_playgrounds"] - } - ] - }, - "realm_playgrounds": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains\ndata about a single playground entry.\n", - "items": { - "$ref": "#/components/schemas/RealmPlayground" - } - } - }, - "example": { - "type": "realm_playgrounds", - "realm_playgrounds": [ - { - "id": 1, - "name": "Python playground", - "pygments_language": "Python", - "url_template": "https://python.example.com" - } - ], - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when\na [custom emoji](/help/custom-emoji) has been updated,\ntypically when a new emoji has been added or an old one\nhas been deactivated. The event contains all custom emoji\nconfigured for the organization, not just the updated\ncustom emoji.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_emoji"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "realm_emoji": { - "type": "object", - "description": "An object in which each key describes a realm emoji.\n", - "additionalProperties": { - "$ref": "#/components/schemas/RealmEmoji" - } - } - }, - "example": { - "type": "realm_emoji", - "op": "update", - "realm_emoji": { - "2": { - "id": "2", - "name": "my_emoji", - "source_url": "/user_avatars/2/emoji/images/2.png", - "deactivated": true, - "author_id": 11 - }, - "1": { - "id": "1", - "name": "green_tick", - "source_url": "/user_avatars/2/emoji/images/1.png", - "deactivated": false, - "author_id": 11 - } - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_domains"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "realm_domain": { - "$ref": "#/components/schemas/RealmDomain" - } - }, - "example": { - "type": "realm_domains", - "op": "add", - "realm_domain": { - "domain": "zulip.org", - "allow_subdomains": false - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_domains"] - } - ] - }, - "op": { - "type": "string", - "enum": ["change"] - }, - "realm_domain": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of the edited domain.\n", - "properties": { - "domain": { - "type": "string", - "description": "The domain whose settings have changed.\n" - }, - "allow_subdomains": { - "type": "boolean", - "description": "Whether subdomains are allowed for this domain.\n" - } - } - } - }, - "example": { - "type": "realm_domains", - "op": "change", - "realm_domain": { - "domain": "zulip.org", - "allow_subdomains": true - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the set of\n[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)\nhas changed.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_domains"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "domain": { - "type": "string", - "description": "The domain to be removed.\n" - } - }, - "example": { - "type": "realm_domains", - "op": "remove", - "domain": "zulip.org", - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to the user who requested a\n[data export](/help/export-your-organization)\nwhen the status of the data export changes.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_export"] - } - ] - }, - "exports": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains\ndetails about a data export of the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), `export_type`\nparameter was not present as only public data export was supported via API.\n", - "items": { - "$ref": "#/components/schemas/RealmExport" - } - } - }, - "example": { - "type": "realm_export", - "exports": [ - { - "id": 107, - "export_time": 1594825443.656797, - "acting_user_id": 10, - "export_url": null, - "deleted_timestamp": null, - "failed_timestamp": 1594825444.436336, - "pending": false, - "export_type": 1 - } - ], - "id": 1 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to administrators when the [data export\nconsent][help-export-consent] status for a user changes, whether due\nto a user changing their consent preferences or a user being created\nor reactivated (since user creation/activation events do not contain\nthese data).\n\n[help-export-consent]: /help/export-your-organization#configure-whether-administrators-can-export-your-private-data\n\n**Changes**: New in Zulip 10.0 (feature level 312). Previously,\nthere was not event available to administrators with these data.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_export_consent"] - } - ] - }, - "user_id": { - "type": "integer", - "description": "The ID of the user whose setting was changed.\n" - }, - "consented": { - "type": "boolean", - "description": "Whether the user has consented for their private data export.\n" - } - }, - "example": { - "type": "realm_export_consent", - "user_id": 1, - "consented": true - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to users who can administer a newly created bot\nuser. Clients will also receive a `realm_user` event that\ncontains basic details (but not the API key).\n\nThe `realm_user` events are sufficient for clients that\nonly need to interact with the bot; this `realm_bot` event\ntype is relevant only for administering bots.\n\nOnly organization administrators and the user who owns the bot will\nreceive this event.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_bot"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "bot": { - "$ref": "#/components/schemas/Bot" - } - }, - "example": { - "type": "realm_bot", - "op": "add", - "bot": { - "email": "test-bot@zulip.testserver", - "user_id": 36, - "full_name": "Foo Bot", - "bot_type": 1, - "is_active": true, - "api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK", - "default_sending_stream": null, - "default_events_register_stream": null, - "default_all_public_streams": false, - "avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1", - "services": [], - "owner_id": 10 - }, - "id": 1 - } - }, - { - "type": "object", - "description": "Event sent to users who can administer a bot user when the bot is\nconfigured. Clients may also receive a `realm_user` event that\nfor changes in public data about the bot (name, etc.).\n\nThe `realm_user` events are sufficient for clients that\nonly need to interact with the bot; this `realm_bot` event\ntype is relevant only for administering bots.\n\nOnly organization administrators and the user who owns the bot will\nreceive this event.\n", - "additionalProperties": false, - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_bot"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "bot": { - "allOf": [ - { - "description": "Object containing details about the changed bot.\nIt contains two properties: the user ID of the bot and\nthe property to be changed. The changed property is one\nof the remaining properties listed below.\n" - }, - { - "$ref": "#/components/schemas/BasicBot" - } - ] - } - }, - "example": { - "type": "realm_bot", - "op": "update", - "bot": { - "user_id": 37, - "services": [ - { - "base_url": "http://hostname.domain2.com", - "interface": 2, - "token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw" - } - ] - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when a bot has been deactivated.\n\n**Changes**: Deprecated and no longer sent since Zulip 8.0 (feature level 222).\n\nPreviously, this event was sent to all users in a Zulip organization when a\nbot was deactivated.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_bot"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "bot": { - "type": "object", - "description": "Object containing details about the deactivated bot.\n", - "additionalProperties": false, - "properties": { - "user_id": { - "type": "integer", - "description": "The user ID of the deactivated bot.\n" - }, - "full_name": { - "type": "string", - "description": "The full name of the deactivated bot.\n" - } - } - } - }, - "example": { - "type": "realm_bot", - "op": "remove", - "bot": { - "user_id": 35, - "full_name": "Foo Bot" - }, - "id": 1 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users when a bot has been deactivated.\nNote that this is very similar to the bot_remove event\nand one of them will be removed soon.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_bot"] - } - ] - }, - "op": { - "type": "string", - "enum": ["delete"] - }, - "bot": { - "type": "object", - "description": "Object containing details about the deactivated bot.\n", - "additionalProperties": false, - "properties": { - "user_id": { - "type": "integer", - "description": "The user ID of the deactivated bot.\n" - } - } - } - }, - "example": { - "type": "realm_bot", - "op": "delete", - "bot": { - "user_id": 35 - }, - "id": 1 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "The simpler of two possible event types sent to all users\nin a Zulip organization when the configuration of the\norganization (realm) has changed.\n\nOften individual settings are migrated from this format to\nthe [realm/update_dict](#realm-update_dict) event format when additional realm\nsettings are added whose values are coupled to each other\nin some way. The specific values supported by this event\ntype are documented in the [realm/update_dict](#realm-update_dict)\ndocumentation.\n\nA correct client implementation should convert these\nevents into the corresponding [realm/update_dict](#realm-update_dict)\nevent and then process that.\n\n**Changes**: Removed `extra_data` optional property in Zulip 10.0\n(feature level 306). The `extra_data` used to include an\n`upload_quota` field when changed property was `plan_type`. The\nserver now sends a standard `realm/update_dict` event for plan\nchanges.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "property": { - "type": "string", - "description": "The name of the property that was changed.\n" - }, - "value": { - "description": "The new value of the property.\n", - "oneOf": [ - { - "type": "string" - }, - { - "type": "boolean" - }, - { - "type": "integer", - "nullable": true - } - ] - } - }, - "example": { - "type": "realm", - "op": "update", - "property": "disallow_disposable_email_addresses", - "value": false, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the\norganization (realm) is deactivated. Its main purpose is to\nflush active longpolling connections so clients can immediately\nshow the organization as deactivated.\n\nClients cannot rely on receiving this event, because they will\nno longer be able to authenticate to the Zulip API due to the\ndeactivation, and thus can miss it if they did not have an active\nlongpolling connection at the moment of deactivation.\n\nCorrect handling of realm deactivations requires that clients\nparse authentication errors from GET /events; if that is done\ncorrectly, the client can ignore this event type and rely on its\nhandling of the `GET /events` request it will do immediately\nafter processing this batch of events.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm"] - } - ] - }, - "op": { - "type": "string", - "enum": ["deactivated"] - }, - "realm_id": { - "type": "integer", - "description": "The ID of the deactivated realm.\n" - } - }, - "example": { - "type": "realm", - "op": "deactivated", - "realm_id": 2, - "id": 0 - } - }, - { - "type": "object", - "description": "Event sent to all the users whenever the Zulip server restarts.\n\nSpecifically, this event is sent whenever the Tornado process\nfor the user is restarted; in particular, this will always happen\nwhen the Zulip server is upgraded.\n\nClients should use this event to update their tracking of the\nserver's capabilities, and to decide if they wish to get a new\nevent queue after a server upgrade. Clients doing so must\nimplement a random delay strategy to spread such restarts over 5\nminutes or more to avoid creating a synchronized thundering herd\neffect.\n\n**Changes**: Removed the `immediate` flag, which was only used by\nweb clients in development, in Zulip 9.0 (feature level 240).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["restart"] - } - ] - }, - "zulip_version": { - "type": "string", - "description": "The Zulip version number, in the format where this appears\nin the [server_settings](/api/get-server-settings) and\n[register](/api/register-queue) responses.\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" - }, - "zulip_merge_base": { - "type": "string", - "description": "The Zulip merge base number, in the format where this appears\nin the [server_settings](/api/get-server-settings) and\n[register](/api/register-queue) responses.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" - }, - "zulip_feature_level": { - "type": "integer", - "description": "The [Zulip feature level](/api/changelog) of the server\nafter the restart.\n\nClients should use this to update their tracking of the\nserver's capabilities, and may choose to refetch their state\nand create a new event queue when the API feature level has\nchanged in a way that the client finds significant. Clients\nchoosing to do so must implement a random delay strategy to\nspread such restarts over 5 or more minutes to avoid creating\na synchronized thundering herd effect.\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" - }, - "server_generation": { - "type": "integer", - "description": "The timestamp at which the server started.\n" - } - }, - "additionalProperties": false, - "example": { - "id": 0, - "server_generation": 1619334181, - "type": "restart", - "zulip_feature_level": 57, - "zulip_version": "5.0-dev-1650-gc3fd37755f", - "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c" - } - }, - { - "type": "object", - "description": "An event which signals the official Zulip web/desktop app to update,\nby reloading the page and fetching a new queue; this will generally\nfollow a `restart` event. Clients which do not obtain their code\nfrom the server (e.g. mobile and terminal clients, which store their\ncode locally) should ignore this event.\n\nClients choosing to reload the application must implement a random\ndelay strategy to spread such restarts over 5 or more minutes to\navoid creating a synchronized thundering herd effect.\n\n**Changes**: New in Zulip 9.0 (feature level 240).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["web_reload_client"] - } - ] - }, - "immediate": { - "type": "boolean", - "description": "Whether the client should fetch a new event queue immediately,\nrather than using a backoff strategy to avoid thundering herds.\nA Zulip development server uses this parameter to reload\nclients immediately.\n" - } - }, - "additionalProperties": false, - "example": { - "id": 0, - "type": "web_reload_client", - "immediate": true - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "The more general of two event types that may be used when\nsending an event to all users in a Zulip organization when\nthe configuration of the organization (realm) has changed.\n\nUnlike the simpler [realm/update](#realm-update) event format, this\nevent type supports multiple properties being changed in a\nsingle event.\n\nThis event is also sent when deactivating or reactivating a user\nfor settings set to anonymous user groups which the user is direct\nmember of. When deactivating the user, event is only sent to users\nwho cannot access the deactivated user.\n\n**Changes**: Starting with Zulip 10.0 (feature level 303), this\nevent can also be sent when deactivating or reactivating a user.\n\nIn Zulip 7.0 (feature level 163), the realm setting\n`email_address_visibility` was removed. It was replaced by a [user\nsetting](/api/update-settings#parameter-email_address_visibility) with\na [realm user default][user-defaults], with the encoding of different\nvalues preserved. Clients can support all versions by supporting the\ncurrent API and treating every user as having the realm's\n`email_address_visibility` value.\n\n[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update_dict"] - }, - "property": { - "type": "string", - "deprecated": true, - "description": "Always `\"default\"`. Present for backwards-compatibility with older\nclients that predate the `update_dict` event style.\n\n**Deprecated** and will be removed in a future release.\n" - }, - "data": { - "type": "object", - "description": "An object containing the properties that have changed.\n\n**Changes**: In Zulip 10.0 (feature level 316), `edit_topic_policy`\nproperty was removed and replaced by `can_move_messages_between_topics_group`\nrealm setting.\n\nIn Zulip 7.0 (feature level 183), the\n`community_topic_editing_limit_seconds` property was removed.\nIt was documented as potentially returned as a changed property\nin this event, but in fact it was only ever returned in the\n[`POST /register`](/api/register-queue) response.\n\nBefore Zulip 6.0 (feature level 150), on changing any of\n`allow_message_editing`, `message_content_edit_limit_seconds`, or\n`edit_topic_policy` settings, this object included all the three settings\nirrespective of which of these settings were changed. Now, a separate event\nis sent for each changed setting.\n", - "properties": { - "allow_message_editing": { - "type": "boolean", - "description": "Whether this organization's [message edit policy][config-message-editing]\nallows editing the content of messages.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n" - }, - "authentication_methods": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/RealmAuthenticationMethod" - }, - "description": "Dictionary of authentication method keys mapped to dictionaries that\ndescribe the properties of the named authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n\nClients should use this to implement server-settings UI to change which\nmethods are enabled for the organization. For authentication UI itself,\nclients should use the pre-authentication metadata returned by\n[`GET /server_settings`](/api/get-server-settings).\n\n**Changes**: In Zulip 9.0 (feature level 243), the values in this\ndictionary were changed. Previously, the values were a simple boolean\nindicating whether the backend is enabled or not.\n" - }, - "can_access_all_users_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to access all users in the\norganization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 225).\n" - } - ] - }, - "can_create_groups": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create user\ngroups in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 299). Previously\n`user_group_edit_policy` field used to control the permission\nto create user groups.\n" - } - ] - }, - "can_create_bots_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create all types of bot users\nin the organization. See also `can_create_write_only_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" - } - ] - }, - "can_create_write_only_bots_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create bot users that\ncan only send messages in the organization, i.e. incoming webhooks,\nin addition to the users who are present in `can_create_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" - } - ] - }, - "can_create_public_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create public\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 264). Previously\n`realm_create_public_stream_policy` field used to control the\npermission to create public channels.\n" - } - ] - }, - "can_create_private_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create private\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 266). Previously\n`realm_create_private_stream_policy` field used to control the\npermission to create private channels.\n" - } - ] - }, - "can_create_web_public_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create web-public\nchannels in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 280). Previously\n`realm_create_web_public_stream_policy` field used to control\nthe permission to create web-public channels.\n" - } - ] - }, - "can_add_custom_emoji_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add custom emoji in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 307). Previously, this\npermission was controlled by the enum `add_custom_emoji_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n\nBefore Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`\nboolean setting controlled this permission; `true` corresponded to `Admins`,\nand `false` to `Everyone`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_add_subscribers_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add subscribers to channels in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 341). Previously, this\npermission was controlled by the enum `invite_to_stream_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_delete_any_message_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete any message in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 281). Previously, this\npermission was limited to administrators only and was uneditable.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_delete_own_message_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete messages that they have sent in the\norganization.\n\n**Changes**: New in Zulip 10.0 (feature level 291). Previously, this\npermission was controlled by the enum `delete_own_message_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.\n\nBefore Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean\nsetting controlled this permission; `true` corresponded to `Everyone`, and\n`false` to `Admins`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_set_delete_message_policy_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `can_delete_any_message_group`\nand `can_delete_own_message_group` permission settings. Note that the user\nmust be a member of both this group and the `can_administer_channel_group`\nof the channel whose message delete settings they want to change.\n\nOrganization administrators can always change these settings of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_set_topics_policy_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `topics_policy` setting. Note that\nthe user must be a member of both this group and the `can_administer_channel_group`\nof the channel whose `topics_policy` they want to change.\n\nOrganization administrators can always change the `topics_policy` setting of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 392).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_invite_users_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to send email invitations for inviting other users\nto the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 321). Previously, this\npermission was controlled by the enum `invite_to_realm_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nBefore Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean\nsetting controlled this permission; `true` corresponded to `Admins`, and\n`false` to `Members`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_mention_many_users_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using mentions in large\nchannels, even when permitted to do so.\n\n**Changes**: New in Zulip 10.0 (feature level 352). Previously, this\npermission was controlled by the enum `wildcard_mention_policy`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_move_messages_between_channels_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one channel to another\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 310). Previously, this\npermission was controlled by the enum `move_messages_between_streams_policy`.\nValues were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`move_messages_between_streams_policy` enum.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_move_messages_between_topics_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one topic to another\nwithin a channel in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 316). Previously, this\npermission was controlled by the enum `edit_topic_policy`. Values were\n1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`edit_topic_policy` enum.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_resolve_topics_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to [resolve topics](/help/resolve-a-topic)\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 367). Previously, permission to\nresolve topics was controlled by the more general\ncan_move_messages_between_topics_group permission for moving messages.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_manage_all_groups": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - } - ] - }, - "can_manage_billing_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to manage plans and billing in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners\nand users with `is_billing_admin` property set to `true` were allowed to\nmanage plans and billing.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "can_summarize_topics_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to use AI summarization.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - } - ] - }, - "create_multiuse_invite_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to create [reusable invitation\nlinks](/help/invite-new-users#create-a-reusable-invitation-link)\nto the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 209).\n" - } - ] - }, - "default_code_block_language": { - "type": "string", - "description": "The default pygments language code to be used for code blocks in this\norganization. If an empty string, no default has been set.\n\n**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant\nthat both `null` and an empty string could represent that no default was\nset for this realm setting in the [`POST /register`](/api/register-queue)\nresponse. The documentation for both that endpoint and this event\nincorrectly stated that the only representation for no default language\nwas `null`. This event in fact uses the empty string to indicate that no\ndefault has been set in all server versions.\n" - }, - "default_language": { - "type": "string", - "description": "The default language for the organization.\n" - }, - "description": { - "type": "string", - "description": "The description of the organization, used on login and registration pages.\n" - }, - "digest_emails_enabled": { - "type": "boolean", - "description": "Whether the organization has enabled [weekly digest emails](/help/digest-emails).\n" - }, - "digest_weekday": { - "type": "integer", - "description": "The day of the week when the organization will send\nits weekly digest email to inactive users.\n" - }, - "direct_message_initiator_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to start a new direct message conversation\ninvolving other non-bot users. Users who are outside this group and attempt\nto send the first direct message to a given collection of recipient users\nwill receive an error, unless all other recipients are bots or the sender.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "direct_message_permission_group": { - "allOf": [ - { - "description": "A [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to fully use direct messages. Users outside\nthis group can only send direct messages to conversations where all the\nrecipients are in this group, are bots, or are the sender, ensuring that\nevery direct message conversation will be visible to at least one user in\nthis group.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "disallow_disposable_email_addresses": { - "type": "boolean", - "description": "Whether the organization disallows disposable email\naddresses.\n" - }, - "email_changes_disabled": { - "type": "boolean", - "description": "Whether users are allowed to change their own email address in this\norganization. This is typically disabled for organizations that\nsynchronize accounts from LDAP or a similar corporate database.\n" - }, - "enable_read_receipts": { - "type": "boolean", - "description": "Whether read receipts is enabled in the organization or not.\n\nIf disabled, read receipt data will be unavailable to clients, regardless\nof individual users' personal read receipt settings. See also the\n`send_read_receipts` setting within `realm_user_settings_defaults`.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n" - }, - "emails_restricted_to_domains": { - "type": "boolean", - "description": "Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)\nthis organization are required to have an email\naddress in one of the `realm_domains` configured for the organization.\n" - }, - "enable_guest_user_dm_warning": { - "type": "boolean", - "description": "Whether clients should show a warning when a user is composing\na DM to a guest user in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 348).\n" - }, - "enable_guest_user_indicator": { - "type": "boolean", - "description": "Whether clients should display \"(guest)\" after the names of\nguest users to prominently highlight their status.\n\n**Changes**: New in Zulip 8.0 (feature level 216).\n" - }, - "enable_spectator_access": { - "type": "boolean", - "description": "Whether web-public channels are enabled in this organization.\n\nCan only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`\n[server setting][server-settings] is enabled on the Zulip\nserver. See also the `can_create_web_public_channel_group`\nrealm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 109).\n" - }, - "giphy_rating": { - "type": "integer", - "description": "Maximum rating of the GIFs that will be retrieved from GIPHY.\n\n**Changes**: New in Zulip 4.0 (feature level 55).\n" - }, - "icon_source": { - "type": "string", - "description": "String indicating whether the organization's\n[profile icon](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the organization's icon.\n\n- \"G\" means generated by Gravatar (the default).\n- \"U\" means uploaded by an organization administrator.\n" - }, - "icon_url": { - "type": "string", - "description": "The URL of the organization's [profile icon](/help/create-your-organization-profile).\n" - }, - "inline_image_preview": { - "type": "boolean", - "description": "Whether this organization has been configured to enable\n[previews of linked images](/help/image-video-and-website-previews).\n" - }, - "inline_url_embed_preview": { - "type": "boolean", - "description": "Whether this organization has been configured to enable\n[previews of linked websites](/help/image-video-and-website-previews).\n" - }, - "invite_required": { - "type": "boolean", - "description": "Whether an invitation is required to join this organization.\n" - }, - "jitsi_server_url": { - "type": "string", - "nullable": true, - "description": "The URL of the custom Jitsi Meet server configured in this organization's\nsettings.\n\n`null`, the default, means that the organization is using the should use the\nserver-level configuration, `server_jitsi_server_url`.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only\navailable as a server-level configuration, and required a server restart to\nchange.\n" - }, - "logo_source": { - "type": "string", - "description": "String indicating whether the organization's\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" - }, - "logo_url": { - "type": "string", - "description": "The URL of the organization's wide logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" - }, - "topics_policy": { - "type": "string", - "enum": [ - "allow_empty_topic", - "disable_empty_topic" - ], - "description": "The organization's default policy for sending channel messages to the\n[empty \"general chat\" topic](/help/general-chat-topic).\n\n- `\"allow_empty_topic\"`: Channel messages can be sent to the empty topic.\n- `\"disable_empty_topic\"`: Channel messages cannot be sent to the empty topic.\n\n**Changes**: New in Zulip 11.0 (feature level 392). Previously, this was\ncontrolled by the boolean realm `mandatory_topics` setting, which is now\ndeprecated.\n" - }, - "mandatory_topics": { - "type": "boolean", - "deprecated": true, - "description": "Whether [topics are required](/help/require-topics) for messages in this\norganization.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now\ncontrolled by the realm `topics_policy` setting.\n" - }, - "max_file_upload_size_mib": { - "type": "integer", - "description": "The new maximum file size that can be uploaded to this Zulip organization.\n\n**Changes**: New in Zulip 10.0 (feature level 306). Previously, this field of\nthe core state did not support being updated via the events system, as it was\ntypically hardcoded for a given Zulip installation.\n" - }, - "message_content_allowed_in_email_notifications": { - "type": "boolean", - "description": "Whether notification emails in this organization are allowed to\ncontain Zulip the message content, or simply indicate that a new\nmessage was sent.\n" - }, - "message_content_delete_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Messages sent more than this many seconds ago cannot be deleted\nwith this organization's\n[message deletion policy](/help/restrict-message-editing-and-deletion).\n\nWill not be 0. A `null` value means no limit: messages can be deleted\nregardless of how long ago they were sent.\n\n**Changes**: No limit was represented using the\nspecial value `0` before Zulip 5.0 (feature level 100).\n" - }, - "message_content_edit_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Messages sent more than this many seconds ago cannot be edited\nwith this organization's\n[message edit policy](/help/restrict-message-editing-and-deletion).\n\nWill not be `0`. A `null` value means no limit, so messages can be edited\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: Before Zulip 6.0 (feature level 138), no limit was\nrepresented using the special value `0`.\n" - }, - "message_edit_history_visibility_policy": { - "type": "string", - "description": "Which type of message edit history is configured to allow users to\naccess [message edit history](/help/view-a-messages-edit-history).\n\n- \"all\" = All edit history is visible.\n- \"moves\" = Only moves are visible.\n- \"none\" = No edit history is visible.\n\n**Changes**: New in Zulip 10.0 (feature level 358), replacing the previous\n`allow_edit_history` boolean setting; `true` corresponds to `all`,\nand `false` to `none`.\n" - }, - "moderation_request_channel_id": { - "type": "integer", - "description": "The ID of the private channel to which messages flagged by users for\nmoderation are sent. Moderators can use this channel to review and\nact on reported content.\n\nWill be `-1` if moderation requests are disabled.\n\nClients should check whether moderation requests are disabled to\ndetermine whether to present a \"report message\" feature in their UI\nwithin a given organization.\n\n**Changes**: New in Zulip 10.0 (feature level 331). Previously,\nno \"report message\" features existed in Zulip.\n" - }, - "move_messages_within_stream_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Messages sent more than this many seconds ago cannot be moved within a\nchannel to another topic by users who have permission to do so based on this\norganization's [topic edit policy](/help/restrict-moving-messages). This\nsetting does not affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so message topics can be\nedited regardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time\nlimit was always 72 hours for users who were not administrators or\nmoderators.\n" - }, - "move_messages_between_streams_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Messages sent more than this many seconds ago cannot be moved between\nchannels by users who have permission to do so based on this organization's\n[message move policy](/help/restrict-moving-messages). This setting does\nnot affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so messages can be moved\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was\nno time limit for moving messages between channels for users with permission\nto do so.\n" - }, - "name": { - "type": "string", - "description": "The name of the organization, used in login pages etc.\n" - }, - "name_changes_disabled": { - "type": "boolean", - "description": "Indicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their name\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" - }, - "night_logo_source": { - "type": "string", - "description": "String indicating whether the organization's dark theme\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" - }, - "night_logo_url": { - "type": "string", - "description": "The URL of the organization's dark theme wide-format logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" - }, - "new_stream_announcements_stream_id": { - "type": "integer", - "description": "The ID of the channel to which automated messages announcing the\n[creation of new channels][new-channel-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed `notifications_stream_id`\nto `new_stream_announcements_stream_id`.\n" - }, - "org_type": { - "type": "integer", - "description": "The [organization type](/help/organization-type)\nfor the realm.\n\n- 0 = Unspecified\n- 10 = Business\n- 20 = Open-source project\n- 30 = Education (non-profit)\n- 35 = Education (for-profit)\n- 40 = Research\n- 50 = Event or conference\n- 60 = Non-profit (registered)\n- 70 = Government\n- 80 = Political group\n- 90 = Community\n- 100 = Personal\n- 1000 = Other\n\n**Changes**: New in Zulip 6.0 (feature level 128).\n" - }, - "plan_type": { - "type": "integer", - "description": "The plan type of the organization.\n\n- 1 = Self-hosted organization (SELF_HOSTED)\n- 2 = Zulip Cloud free plan (LIMITED)\n- 3 = Zulip Cloud Standard plan (STANDARD)\n- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)\n" - }, - "presence_disabled": { - "type": "boolean", - "description": "Whether online presence of other users is shown in this\norganization.\n" - }, - "push_notifications_enabled": { - "type": "boolean", - "description": "Whether push notifications are enabled for this organization. Typically\n`true` for Zulip Cloud and self-hosted realms that have a valid\nregistration for the [Mobile push notifications\nservice](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),\nand `false` for self-hosted servers that do not.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\nPreviously, this value was never updated via events.\n" - }, - "push_notifications_enabled_end_timestamp": { - "type": "integer", - "nullable": true, - "description": "If the server expects the realm's push notifications access to end at a\ndefinite time in the future, the time at which this is expected to happen.\nMobile clients should use this field to display warnings to users when the\nindicated timestamp is near.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\n" - }, - "require_e2ee_push_notifications": { - "type": "boolean", - "description": "Whether this realm is configured to disallow sending mobile\npush notifications with message content through the legacy\nmobile push notifications APIs. The new API uses end-to-end\nencryption to protect message content and metadata from\nbeing accessible to the push bouncer service, APNs, and\nFCM. Clients that support the new E2EE API will use it\nautomatically regardless of this setting.\n\nIf `true`, mobile push notifications sent to clients that\nlack support for E2EE push notifications will always have\n\"New message\" as their content. Note that these legacy\nmobile notifications will still contain metadata, which may\ninclude the message's ID, the sender's name, email address,\nand avatar.\n\nIn a future release, once the official mobile apps have\nimplemented fully validated their E2EE protocol support,\nthis setting will become strict, and disable the legacy\nprotocol entirely.\n\n**Changes**: New in Zulip 11.0 (feature level 409). Previously,\nthis behavior was available only via the\n`PUSH_NOTIFICATION_REDACT_CONTENT` global server setting.\n" - }, - "require_unique_names": { - "type": "boolean", - "description": "Indicates whether the organization is configured to require users to have\nunique full names. If true, the server will reject attempts to create a\nnew user, or change the name of an existing user, where doing so would\nlead to two users whose names are identical modulo case and unicode\nnormalization.\n\n**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip\nserver could not be configured to enforce unique names.\n" - }, - "send_welcome_emails": { - "type": "boolean", - "description": "Whether or not this organization is configured to send the standard Zulip\n[welcome emails](/help/disable-welcome-emails) to new users joining the organization.\n" - }, - "signup_announcements_stream_id": { - "type": "integer", - "description": "The ID of the channel to which automated messages announcing\nthat [new users have joined the organization][new-user-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-user-announce]: /help/configure-automated-notices#new-user-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed\n`signup_notifications_stream_id` to `signup_announcements_stream_id`.\n" - }, - "upload_quota_mib": { - "type": "integer", - "nullable": true, - "description": "The new upload quota for the Zulip organization.\n\nIf `null`, there is no limit.\n\n**Changes**: New in Zulip 10.0 (feature level 306). Previously,\nthis was present changed via an `upload_quota` field in `extra_data` property\nof [realm/update](#realm-update) event format for `plan_type` events.\n" - }, - "video_chat_provider": { - "type": "integer", - "description": "The configured [video call provider](/help/configure-call-provider) for the\norganization.\n\n- 0 = None\n- 1 = Jitsi Meet\n- 3 = Zoom (User OAuth integration)\n- 4 = BigBlueButton\n- 5 = Zoom (Server to Server OAuth integration)\n\nNote that only one of the [Zoom integrations][zoom-video-calls] can\nbe configured on a Zulip server.\n\n**Changes**: In Zulip 10.0 (feature level 353), added the Zoom Server\nto Server OAuth option.\n\nIn Zulip 3.0 (feature level 1), added the None option\nto disable video call UI.\n\n[zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom\n" - }, - "waiting_period_threshold": { - "type": "integer", - "description": "Members whose accounts have been created at least this many days ago\nwill be treated as [full members][calc-full-member]\nfor the purpose of settings that restrict access to new members.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "want_advertise_in_communities_directory": { - "type": "boolean", - "description": "Whether the organization has given permission to be advertised in the\nZulip [communities directory](/help/communities-directory).\n\n**Changes**: New in Zulip 6.0 (feature level 129).\n" - }, - "welcome_message_custom_text": { - "type": "string", - "description": "This organization's configured custom message for Welcome Bot\nto send to new user accounts, in Zulip Markdown format.\n\nMaximum length is 8000 characters.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n" - }, - "zulip_update_announcements_stream_id": { - "type": "integer", - "description": "The ID of the channel to which automated messages announcing\nnew features or other end-user updates about the Zulip software are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n**Changes**: New in Zulip 9.0 (feature level 242).\n" - } - }, - "additionalProperties": false - } - }, - "example": { - "type": "realm", - "op": "update_dict", - "property": "default", - "data": { - "message_content_edit_limit_seconds": 600 - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to all users in a Zulip organization when the\n[default settings for new users][new-user-defaults]\nof the organization (realm) have changed.\n\n[new-user-defaults]: /help/configure-default-new-user-settings\n\nSee [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)\nfor details on possible properties.\n\n**Changes**: New in Zulip 5.0 (feature level 95).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["realm_user_settings_defaults"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "property": { - "type": "string", - "description": "The name of the property that was changed.\n" - }, - "value": { - "description": "The new value of the property.\n", - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "integer" - }, - { - "type": "string" - } - ] - } - }, - "example": { - "type": "realm_user_settings_defaults", - "op": "update", - "property": "left_side_userlist", - "value": false, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details of newly created drafts.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["drafts"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "drafts": { - "type": "array", - "description": "An array containing objects for the newly created drafts.\n", - "items": { - "$ref": "#/components/schemas/Draft" - } - } - }, - "example": { - "type": "drafts", - "op": "add", - "drafts": [ - { - "id": 17, - "type": "private", - "to": [6], - "topic": "", - "content": "Hello there!", - "timestamp": 15954790200 - } - ] - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details for an edited draft.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["drafts"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "draft": { - "$ref": "#/components/schemas/Draft" - } - }, - "example": { - "type": "drafts", - "op": "update", - "draft": { - "id": 17, - "type": "private", - "to": [6, 7, 8, 9, 10], - "topic": "", - "content": "Hello everyone!", - "timestamp": 15954790200 - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing the ID of a deleted draft.\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["drafts"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "draft_id": { - "type": "integer", - "description": "The ID of the draft that was just deleted.\n" - } - }, - "example": { - "type": "drafts", - "op": "remove", - "draft_id": 17 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details of a newly configured navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["navigation_view"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "navigation_view": { - "$ref": "#/components/schemas/NavigationView" - } - }, - "example": { - "type": "navigation_view", - "op": "add", - "navigation_view": { - "fragment": "narrow/is/alerted", - "is_pinned": true, - "name": "Alert Words" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details of an update to an existing navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["navigation_view"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "fragment": { - "type": "string", - "description": "The unique URL hash of the navigation view being updated.\n" - }, - "data": { - "type": "object", - "additionalProperties": false, - "description": "A dictionary containing the updated properties of the navigation view.\n", - "properties": { - "name": { - "type": "string", - "nullable": true, - "description": "The user-facing name for custom navigation views. Omit this field for built-in views.\n" - }, - "is_pinned": { - "type": "boolean", - "nullable": true, - "description": "Determines whether the view is pinned (true) or hidden in the menu (false).\n" - } - } - } - }, - "example": { - "type": "navigation_view", - "op": "update", - "fragment": "narrow/is/alerted", - "data": { - "is_pinned": false - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing the fragment of a deleted navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["navigation_view"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "fragment": { - "type": "string", - "description": "The unique URL hash of the navigation view that was just deleted.\n" - } - }, - "example": { - "type": "navigation_view", - "op": "remove", - "fragment": "narrow/is/mentioned" - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details of a newly created saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["saved_snippets"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "saved_snippet": { - "$ref": "#/components/schemas/SavedSnippet" - } - }, - "example": { - "type": "saved_snippets", - "op": "add", - "saved_snippet": { - "id": 1, - "title": "Example", - "content": "Welcome to the organization.", - "date_created": 1681662420 - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing details of the edited saved snippet.\n\nClients should update the existing saved snippet with the\nID provided in the `saved_snippet` object.\n\n**Changes**: New in Zulip 10.0 (feature level 368).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["saved_snippets"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "saved_snippet": { - "$ref": "#/components/schemas/SavedSnippet" - } - }, - "example": { - "type": "saved_snippets", - "op": "update", - "saved_snippet": { - "id": 1, - "title": "Example", - "content": "Welcome to the organization.", - "date_created": 1681662420 - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event containing the ID of a deleted saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["saved_snippets"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "saved_snippet_id": { - "type": "integer", - "description": "The ID of the saved snippet that was just deleted.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" - } - }, - "example": { - "type": "saved_snippets", - "op": "remove", - "saved_snippet_id": 17 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when a reminder is scheduled.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["reminders"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "reminders": { - "type": "array", - "description": "An array of objects containing details of the newly created\nreminders.\n", - "items": { - "$ref": "#/components/schemas/Reminder" - } - } - }, - "example": { - "type": "reminders", - "op": "add", - "reminders": [ - { - "reminder_id": 17, - "type": "private", - "to": [6], - "content": "Hello there!", - "rendered_content": "

Hello there!

", - "scheduled_delivery_timestamp": 1681662420, - "failed": false, - "reminder_target_message_id": 42 - } - ] - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when a reminder\nis deleted.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["reminders"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "reminder_id": { - "type": "integer", - "description": "The ID of the reminder that was deleted.\n" - } - }, - "example": { - "type": "reminders", - "op": "remove", - "reminder_id": 17 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when scheduled messages\nare created.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["scheduled_messages"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "scheduled_messages": { - "type": "array", - "description": "An array of objects containing details of the newly created\nscheduled messages.\n", - "items": { - "$ref": "#/components/schemas/ScheduledMessage" - } - } - }, - "example": { - "type": "scheduled_messages", - "op": "add", - "scheduled_messages": [ - { - "scheduled_message_id": 17, - "type": "private", - "to": [6], - "content": "Hello there!", - "rendered_content": "

Hello there!

", - "scheduled_delivery_timestamp": 1681662420, - "failed": false - } - ] - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when a scheduled message\nis edited.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["scheduled_messages"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "scheduled_message": { - "$ref": "#/components/schemas/ScheduledMessage" - } - }, - "example": { - "type": "scheduled_messages", - "op": "update", - "scheduled_message": { - "scheduled_message_id": 17, - "type": "private", - "to": [6], - "content": "Hello there!", - "rendered_content": "

Hello there!

", - "scheduled_delivery_timestamp": 1681662420, - "failed": false - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to a user's clients when a scheduled message\nis deleted.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["scheduled_messages"] - } - ] - }, - "op": { - "type": "string", - "enum": ["remove"] - }, - "scheduled_message_id": { - "type": "integer", - "description": "The ID of the scheduled message that was deleted.\n" - } - }, - "example": { - "type": "scheduled_messages", - "op": "remove", - "scheduled_message_id": 17 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to users in an organization when a channel folder is created.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["channel_folder"] - } - ] - }, - "op": { - "type": "string", - "enum": ["add"] - }, - "channel_folder": { - "$ref": "#/components/schemas/ChannelFolder" - } - }, - "example": { - "type": "channel_folder", - "op": "add", - "channel_folder": { - "name": "fronted", - "creator_id": 9, - "date_created": 1717484476, - "description": "Channels for frontend discussions", - "rendered_description": "

Channels for frontend discussions

", - "order": 1, - "id": 2, - "is_archived": false - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to users in an organization when a channel folder is updated.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["channel_folder"] - } - ] - }, - "op": { - "type": "string", - "enum": ["update"] - }, - "channel_folder_id": { - "type": "number", - "description": "ID of the updated channel folder.\n" - }, - "data": { - "type": "object", - "additionalProperties": false, - "description": "Dictionary containing the changed details of the channel folder.\n", - "properties": { - "name": { - "type": "string", - "description": "The new name of the channel folder. Only present if the channel\nfolder's name changed.\n" - }, - "description": { - "type": "string", - "description": "The new description of the channel folder. Only present if the\ndescription changed.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "rendered_description": { - "type": "string", - "description": "The new rendered description of the channel folder. Only present\nif the description changed.\n" - }, - "is_archived": { - "type": "boolean", - "description": "Whether the channel folder is archived or not. Only present if\nthe channel folder is archived or unarchived.\n" - } - } - } - }, - "example": { - "type": "channel_folder", - "op": "update", - "data": { - "name": "New frontend" - }, - "id": 0 - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "Event sent to users in an organization when channel folders are reordered.\n\n**Changes**: New in Zulip 11.0 (feature level 418).\n", - "properties": { - "id": { - "$ref": "#/components/schemas/EventIdSchema" - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EventTypeSchema" - }, - { - "enum": ["channel_folder"] - } - ] - }, - "op": { - "type": "string", - "enum": ["reorder"] - }, - "order": { - "type": "array", - "description": "A list of channel folder IDs representing the new order.\n", - "items": { - "type": "integer" - } - } - }, - "example": { - "type": "channel_folder", - "op": "reorder", - "order": [3, 1, 2], - "id": 0 - } - } - ] - } - }, - "queue_id": { - "type": "string", - "description": "The ID of the registered queue.\n" - } - }, - "example": { - "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", - "events": [ - { - "id": 0, - "message": { - "avatar_url": "https://url/for/othello-bots/avatar", - "client": "website", - "content": "I come not, friends, to steal away your hearts.", - "content_type": "text/x-markdown", - "display_recipient": "Denmark", - "id": 12345678, - "recipient_id": 12314, - "sender_email": "othello-bot@example.com", - "sender_full_name": "Othello Bot", - "sender_id": 13215, - "sender_realm_str": "example", - "topic_links": [], - "timestamp": 1375978403, - "type": "stream" - }, - "type": "message" - }, - { - "id": 1, - "message": { - "avatar_url": "https://url/for/othello-bots/avatar", - "client": "website", - "content": "With mirth and laughter let old wrinkles come.", - "content_type": "text/x-markdown", - "display_recipient": [ - { - "email": "hamlet@example.com", - "full_name": "Hamlet of Denmark", - "id": 31572 - } - ], - "id": 12345679, - "recipient_id": 18391, - "sender_email": "othello-bot@example.com", - "sender_full_name": "Othello Bot", - "sender_id": 13215, - "sender_realm_str": "example", - "subject": "", - "topic_links": [], - "timestamp": 1375978404, - "type": "private" - }, - "type": "message" - } - ], - "msg": "", - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/BadEventQueueIdError" - }, - { - "description": "#### BAD_EVENT_QUEUE_ID errors\n\nThis error occurs if the target event queue has been garbage collected.\nA compliant client will handle this error by re-initializing itself\n(e.g. a Zulip web app browser window will reload in this case).\n\nSee [the /register endpoint docs](/api/register-queue) for details on how to\nhandle these correctly.\n\nThe following is the error response in such case:\n" - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "delete-queue", - "summary": "Delete an event queue", - "tags": ["real_time_events"], - "description": "Delete a previously registered queue.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "queue_id": { - "description": "The ID of an event queue that was previously registered via\n`POST /api/v1/register` (see [Register a queue](/api/register-queue)).\n", - "type": "string", - "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8" - } - }, - "required": ["queue_id"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/BadEventQueueIdError" - }, - { - "description": "A typical JSON response for when the `queue_id` is non-existent or the\nassociated queue has already been deleted:\n" - } - ] - } - } - } - } - } - } - }, - "/get_stream_id": { - "get": { - "operationId": "get-stream-id", - "summary": "Get channel ID", - "tags": ["channels"], - "description": "Get the unique ID of a given channel.\n", - "parameters": [ - { - "name": "stream", - "in": "query", - "description": "The name of the channel to access.\n", - "schema": { - "type": "string" - }, - "example": "Denmark", - "required": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "stream_id": { - "type": "integer", - "description": "The ID of the given channel.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "stream_id": 15 - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid channel name 'nonexistent'", - "result": "error" - }, - "description": "An example JSON response for when the supplied channel does not exist:\n" - } - ] - } - } - } - } - } - } - }, - "/mark_all_as_read": { - "post": { - "deprecated": true, - "operationId": "mark-all-as-read", - "summary": "Mark all messages as read", - "tags": ["messages"], - "description": "Marks all of the current user's unread messages as read.\n\nBecause this endpoint marks messages as read in batches, it is possible\nfor the request to time out after only marking some messages as read.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages were marked as read, then the success response\nwill return `\"complete\": true`.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n\nBefore Zulip 8.0 (feature level 211), if the server's\nprocessing was interrupted by a timeout, but some messages were marked\nas read, then it would return `\"result\": \"partially_completed\"`, along\nwith a `code` field for an error string, in the success response to\nindicate that there was a timeout and that the client should repeat the\nrequest.\n\nBefore Zulip 6.0 (feature level 153), this request did a single atomic\noperation, which could time out with 10,000s of unread messages to mark\nas read. As of this feature level, messages are marked as read in\nbatches, starting with the newest messages, so that progress is made\neven if the request times out. And, instead of returning an error when\nthe request times out and some messages have been marked as read, a\nsuccess response with `\"result\": \"partially_completed\"` is returned.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": ["complete"], - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "complete": { - "type": "boolean", - "description": "Whether all unread messages were marked as read.\n\nWill be `false` if the request successfully marked\nsome, but not all, messages as read.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "complete": true - } - } - ] - } - } - } - } - } - } - }, - "/mark_stream_as_read": { - "post": { - "deprecated": true, - "operationId": "mark-stream-as-read", - "summary": "Mark messages in a channel as read", - "tags": ["messages"], - "description": "Mark all the unread messages in a channel as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the channel to access.\n", - "type": "integer", - "example": 43 - } - }, - "required": ["stream_id"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/mark_topic_as_read": { - "post": { - "deprecated": true, - "operationId": "mark-topic-as-read", - "summary": "Mark messages in a topic as read", - "tags": ["messages"], - "description": "Mark all the unread messages in a topic as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the channel to access.\n", - "type": "integer", - "example": 43 - }, - "topic_name": { - "description": "The name of the topic whose messages should be marked as read.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", - "type": "string", - "example": "new coffee machine" - } - }, - "required": ["stream_id", "topic_name"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/attachments": { - "get": { - "operationId": "get-attachments", - "summary": "Get attachments", - "tags": ["users"], - "description": "Fetch metadata on files uploaded by the requesting user.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "attachments": { - "type": "array", - "description": "A list of `attachment` objects, each containing\ndetails about a file uploaded by the user.\n", - "items": { - "$ref": "#/components/schemas/Attachment" - } - }, - "upload_space_used": { - "type": "integer", - "description": "The total size of all files uploaded by users in the organization,\nin bytes.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "attachments": [ - { - "id": 1, - "name": "166050.jpg", - "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg", - "size": 571946, - "create_time": 1588145417000, - "messages": [ - { - "id": 102, - "date_sent": 1588145424000 - }, - { - "id": 103, - "date_sent": 1588145448000 - } - ] - } - ], - "upload_space_used": 571946 - } - } - ] - } - } - } - } - } - } - }, - "/attachments/{attachment_id}": { - "delete": { - "operationId": "remove-attachment", - "summary": "Delete an attachment", - "tags": ["users"], - "description": "Delete an uploaded file given its attachment ID.\n\nNote that uploaded files that have been referenced in at least\none message are automatically deleted once the last message\ncontaining a link to them is deleted (whether directly or via\na [message retention policy](/help/message-retention-policy)).\n\nUploaded files that are never used in a message are\nautomatically deleted a few weeks after being uploaded.\n\nAttachment IDs can be contained from [GET /attachments](/api/get-attachments).\n", - "parameters": [ - { - "name": "attachment_id", - "in": "path", - "description": "The ID of the attachment to be deleted.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid attachment", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for when the `attachment_id` is invalid\n" - } - ] - } - ] - } - } - } - }, - "401": { - "description": "Error.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "UNAUTHORIZED", - "result": "error", - "msg": "Not logged in: API authentication or user session required" - }, - "description": "A typical failed JSON response for when the user is not logged in:\n" - } - ] - } - } - } - } - } - } - }, - "/drafts": { - "get": { - "operationId": "get-drafts", - "tags": ["drafts"], - "summary": "Get drafts", - "description": "Fetch all drafts for the current user.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "count": { - "type": "integer", - "description": "The number of drafts the user currently has. Also the\nnumber of drafts returned under \"drafts\".\n", - "example": 3 - }, - "drafts": { - "type": "array", - "description": "Returns all of the current user's drafts, in order of last edit time\n(with the most recently edited draft appearing first).\n", - "items": { - "$ref": "#/components/schemas/Draft" - } - } - }, - "example": { - "result": "success", - "msg": "", - "count": 3, - "drafts": [ - { - "id": 1, - "type": "stream", - "to": [3], - "topic": "sync drafts", - "content": "Let's add backend support for syncing drafts.", - "timestamp": 1595479019 - }, - { - "id": 2, - "type": "private", - "to": [4], - "topic": "", - "content": "What if we made it possible to sync drafts in Zulip?", - "timestamp": 1595479019 - }, - { - "id": 3, - "type": "private", - "to": [4, 10], - "topic": "", - "content": "What if we made it possible to sync drafts in Zulip?", - "timestamp": 1595479019 - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "create-drafts", - "tags": ["drafts"], - "summary": "Create drafts", - "description": "Create one or more drafts on the server. These drafts will be automatically\nsynchronized to other clients via `drafts` events.\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "drafts": { - "description": "A JSON-encoded list of containing new draft objects.\n", - "type": "array", - "items": { - "$ref": "#/components/schemas/Draft" - }, - "example": [ - { - "type": "stream", - "to": [1], - "topic": "questions", - "content": "What are the contribution guidelines for this project?", - "timestamp": 1595479019 - } - ] - } - } - }, - "encoding": { - "drafts": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "ids": { - "type": "array", - "description": "An array of the IDs for the drafts that were just created in the same\norder as they were submitted.\n", - "items": { - "type": "integer" - } - } - }, - "example": { - "result": "success", - "msg": "", - "ids": [1, 2, 3] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "JSON response for when a draft targeted towards a channel does not specify\nexactly one channel ID:\n", - "example": { - "code": "BAD_REQUEST", - "msg": "Must specify exactly 1 channel ID for channel messages", - "result": "error" - } - } - ] - } - } - } - } - } - } - }, - "/drafts/{draft_id}": { - "patch": { - "operationId": "edit-draft", - "tags": ["drafts"], - "summary": "Edit a draft", - "description": "Edit a draft on the server. The edit will be automatically\nsynchronized to other clients via `drafts` events.\n", - "parameters": [ - { - "name": "draft_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the draft to be edited.\n", - "required": true, - "example": 2 - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "draft": { - "allOf": [ - { - "$ref": "#/components/schemas/Draft" - }, - { - "description": "A JSON-encoded object containing a replacement draft object for this ID.\n", - "example": { - "type": "stream", - "to": [1], - "topic": "questions", - "content": "how tough is a Lamy Safari?", - "timestamp": 1595479019 - } - } - ] - } - }, - "required": ["draft"] - }, - "encoding": { - "draft": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no draft exists with\nthe provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Draft does not exist" - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "delete-draft", - "tags": ["drafts"], - "summary": "Delete a draft", - "description": "Delete a single draft from the server. The deletion will be automatically\nsynchronized to other clients via a `drafts` event.\n", - "parameters": [ - { - "name": "draft_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the draft you want to delete.\n", - "required": true, - "example": 1 - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no draft exists with\nthe provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Draft does not exist" - } - } - ] - } - } - } - } - } - } - }, - "/navigation_views": { - "get": { - "operationId": "get-navigation-views", - "tags": ["navigation_views"], - "summary": "Get all navigation views", - "description": "Fetch all configured custom navigation views for the current user.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "navigation_views": { - "type": "array", - "description": "An array of dictionaries containing the user's navigation views.\n", - "items": { - "$ref": "#/components/schemas/NavigationView" - } - } - }, - "example": { - "result": "success", - "msg": "", - "navigation_views": [ - { - "fragment": "narrow/is/alerted", - "is_pinned": false, - "name": "Alert Words" - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "add-navigation-view", - "tags": ["navigation_views"], - "summary": "Add a navigation view", - "description": "Adds a new custom left sidebar navigation view configuration\nfor the current user.\n\nThis can be used both to configure built-in navigation views,\nor to add new navigation views.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "$ref": "#/components/schemas/NavigationView" - } - } - } - }, - "responses": { - "200": { - "description": "Request succeeded.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "type": "object", - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {} - }, - "example": { - "result": "success", - "msg": "" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CodedError" - }, - "examples": { - "invalid_parameters": { - "value": { - "code": "BAD_REQUEST", - "msg": "fragment cannot be blank", - "result": "error" - } - } - } - } - } - } - } - } - }, - "/navigation_views/{fragment}": { - "patch": { - "operationId": "edit-navigation-view", - "tags": ["navigation_views"], - "summary": "Update the navigation view", - "description": "Update the details of an existing configured navigation view,\nsuch as its name or whether it's pinned.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "parameters": [ - { - "name": "fragment", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The unique URL hash of the navigation view to be updated.\n\nThis also serves as the identifier for the navigation view.\n", - "example": "narrow/is/alerted" - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "is_pinned": { - "type": "boolean", - "description": "Determines whether the view is pinned (true) or hidden in\nthe menu (false).\n", - "example": true - }, - "name": { - "type": "string", - "description": "The user-facing name for custom navigation views. Omit this\nfield for built-in views.\n", - "example": "Watched Phrases" - } - }, - "anyOf": [ - { - "required": ["is_pinned"] - }, - { - "required": ["name"] - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {} - }, - "example": { - "result": "success", - "msg": "" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Built-in views cannot have a custom name", - "result": "error" - } - } - ], - "description": "A typical failed JSON response for invalid parameters.\n" - } - } - } - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response when no navigation view\nexists with the provided fragment:\n", - "example": { - "code": "NOT_FOUND", - "result": "error", - "msg": "Navigation view does not exist." - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "remove-navigation-view", - "tags": ["navigation_views"], - "summary": "Remove a navigation view", - "description": "Remove a navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "parameters": [ - { - "name": "fragment", - "in": "path", - "schema": { - "type": "string" - }, - "description": "The unique URL hash of the navigation view to be removed.\n\nThis also serves as the identifier for the navigation view.\n", - "example": "narrow/is/alerted", - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no navigation\nview exists with the provided fragment:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Navigation view does not exist." - } - } - ] - } - } - } - } - } - } - }, - "/saved_snippets": { - "get": { - "operationId": "get-saved-snippets", - "tags": ["drafts"], - "summary": "Get all saved snippets", - "description": "Fetch all the saved snippets for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "saved_snippets": { - "type": "array", - "description": "An array of dictionaries containing data on all of the current user's\nsaved snippets.\n", - "items": { - "$ref": "#/components/schemas/SavedSnippet" - } - } - }, - "example": { - "result": "success", - "msg": "", - "saved_snippets": [ - { - "id": 1, - "title": "Example", - "content": "Welcome to the organization.", - "date_created": 1681662420 - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "create-saved-snippet", - "tags": ["drafts"], - "summary": "Create a saved snippet", - "description": "Create a new saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the saved snippet.\n", - "example": "Example title" - }, - "content": { - "type": "string", - "description": "The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n", - "example": "Welcome to the organization." - } - }, - "required": ["title", "content"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "saved_snippet_id": { - "type": "integer", - "description": "The unique ID of the saved snippet created.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "saved_snippet_id": 1 - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Title cannot be empty.", - "result": "error" - }, - "description": "A typical failed JSON response for when either title or content is\nempty:\n" - } - ] - } - } - } - } - } - } - }, - "/saved_snippets/{saved_snippet_id}": { - "patch": { - "operationId": "edit-saved-snippet", - "tags": ["drafts"], - "summary": "Edit a saved snippet", - "description": "Edit a saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 368).\n", - "parameters": [ - { - "name": "saved_snippet_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the saved snippet to edit.\n", - "required": true, - "example": 3 - } - ], - "requestBody": { - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the saved snippet.\n", - "example": "Welcome message" - }, - "content": { - "type": "string", - "description": "The content of the saved snippet in the original [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n", - "example": "Welcome to the organization." - } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no saved snippet exists\nwith the provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Saved snippet does not exist." - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "delete-saved-snippet", - "tags": ["drafts"], - "summary": "Delete a saved snippet", - "description": "Delete a saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n", - "parameters": [ - { - "name": "saved_snippet_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the saved snippet to delete.\n", - "required": true, - "example": 2 - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no saved snippet exists\nwith the provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Saved snippet does not exist." - } - } - ] - } - } - } - } - } - } - }, - "/reminders": { - "get": { - "operationId": "get-reminders", - "tags": ["reminders"], - "summary": "Get reminders", - "description": "Fetch all [reminders](/help/schedule-a-reminder) for the\ncurrent user.\n\nReminders are messages the user has scheduled to be sent in the\nfuture to themself.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "reminders": { - "type": "array", - "description": "Returns all of the current user's undelivered reminders,\nordered by `scheduled_delivery_timestamp` (ascending).\n", - "items": { - "$ref": "#/components/schemas/Reminder" - } - } - }, - "example": { - "result": "success", - "msg": "", - "reminders": [ - { - "reminder_id": 27, - "to": [6], - "type": "private", - "content": "Hi", - "rendered_content": "

Hi

", - "scheduled_delivery_timestamp": 1681662420, - "failed": false, - "reminder_target_message_id": 42 - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "create-message-reminder", - "tags": ["reminders"], - "summary": "Create a message reminder", - "description": "Schedule a reminder to be sent to the current user at the specified time. The reminder will link the relevant message.\n\n**Changes**: New in Zulip 11.0 (feature level 381).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "message_id": { - "description": "The ID of the previously sent message to reference in the reminder message.\n", - "type": "integer", - "example": 1 - }, - "scheduled_delivery_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the reminder will be sent,\nin UTC seconds.\n", - "example": 5681662420 - }, - "note": { - "type": "string", - "description": "A note associated with the reminder shown in the Notification Bot message.\n\n**Changes**: New in Zulip 11.0 (feature level 415).\n", - "example": "This is a reminder note." - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "reminder_id": { - "type": "integer", - "description": "Unique ID of the scheduled message reminder.\n" - } - }, - "example": { - "msg": "", - "reminder_id": 42, - "result": "success" - } - } - ] - } - } - } - } - } - } - }, - "/reminders/{reminder_id}": { - "delete": { - "operationId": "delete-reminder", - "tags": ["reminders"], - "summary": "Delete a reminder", - "description": "Delete, and therefore cancel sending, a previously [scheduled\nreminder](/help/schedule-a-reminder).\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", - "parameters": [ - { - "name": "reminder_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the reminder to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", - "required": true, - "example": 1 - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no reminder exists\nwith the provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Reminder does not exist" - } - } - ] - } - } - } - } - } - } - }, - "/scheduled_messages": { - "get": { - "operationId": "get-scheduled-messages", - "tags": ["scheduled_messages"], - "summary": "Get scheduled messages", - "description": "Fetch all [scheduled messages](/help/schedule-a-message) for\nthe current user.\n\nScheduled messages are messages the user has scheduled to be\nsent in the future via the send later feature.\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "scheduled_messages": { - "type": "array", - "description": "Returns all of the current user's undelivered scheduled\nmessages, ordered by `scheduled_delivery_timestamp`\n(ascending).\n", - "items": { - "$ref": "#/components/schemas/ScheduledMessage" - } - } - }, - "example": { - "result": "success", - "msg": "", - "scheduled_messages": [ - { - "scheduled_message_id": 27, - "to": 14, - "type": "stream", - "content": "Hi", - "rendered_content": "

Hi

", - "topic": "Introduction", - "scheduled_delivery_timestamp": 1681662420, - "failed": false - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "create-scheduled-message", - "tags": ["scheduled_messages"], - "summary": "Create a scheduled message", - "description": "Create a new [scheduled message](/help/schedule-a-message).\n\n**Changes**: In Zulip 7.0 (feature level 184), moved support for\n[editing a scheduled message](/api/update-scheduled-message) to a\nseparate API endpoint, which removed the `scheduled_message_id`\nparameter from this endpoint.\n\nNew in Zulip 7.0 (feature level 179).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "type": { - "description": "The type of scheduled message to be sent. `\"direct\"` for a direct\nmessage and `\"stream\"` or `\"channel\"` for a channel message.\n\nNote that, while `\"private\"` is supported for scheduling direct\nmessages, clients are encouraged to use to the modern convention of\n`\"direct\"` to indicate this message type, because support for\n`\"private\"` may eventually be removed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate the type of a channel\nmessage.\n", - "type": "string", - "enum": ["direct", "channel", "stream", "private"], - "example": "direct" - }, - "to": { - "description": "The scheduled message's tentative target audience.\n\nFor channel messages, the integer ID of the channel.\nFor direct messages, a list containing integer user IDs.\n", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "integer" - }, - "minLength": 1 - } - ], - "example": [9, 10] - }, - "content": { - "$ref": "#/components/schemas/RequiredContent" - }, - "topic": { - "description": "The topic of the message. Only required for channel messages\n(`\"type\": \"stream\"` or `\"type\": \"channel\"`), ignored otherwise.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", - "type": "string", - "example": "Castle" - }, - "scheduled_delivery_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message will be sent,\nin UTC seconds.\n", - "example": 3165826990 - }, - "read_by_sender": { - "type": "boolean", - "description": "Whether the message should be initially marked read by its\nsender. If unspecified, the server uses a heuristic based\non the client name and the recipient.\n\n**Changes**: New in Zulip 8.0 (feature level 236).\n", - "example": true - } - }, - "required": [ - "type", - "to", - "content", - "scheduled_delivery_timestamp" - ] - }, - "encoding": { - "to": { - "contentType": "application/json" - }, - "scheduled_delivery_timestamp": { - "contentType": "application/json" - }, - "read_by_sender": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "scheduled_message_id": { - "type": "integer", - "description": "The unique ID of the scheduled message.\n\nThis is different from the unique ID that the message will have\nafter it is sent.\n" - } - }, - "example": { - "msg": "", - "scheduled_message_id": 42, - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/NonExistingChannelIdError" - }, - { - "description": "A typical failed JSON response for when a channel message is scheduled\nto be sent to a channel that does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid user ID 10", - "result": "error" - }, - "description": "A typical failed JSON response for when a direct message is scheduled\nto be sent to a user that does not exist:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/scheduled_messages/{scheduled_message_id}": { - "patch": { - "operationId": "update-scheduled-message", - "tags": ["scheduled_messages"], - "summary": "Edit a scheduled message", - "description": "Edit an existing [scheduled message](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 184).\n", - "parameters": [ - { - "name": "scheduled_message_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the scheduled message to update.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", - "required": true, - "example": 2 - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "type": { - "description": "The type of scheduled message to be sent. `\"direct\"` for a direct\nmessage and `\"stream\"` or `\"channel\"` for a channel message.\n\nWhen updating the type of the scheduled message, the `to` parameter\nis required. And, if updating the type of the scheduled message to\n`\"stream\"`/`\"channel\"`, then the `topic` parameter is also required.\n\nNote that, while `\"private\"` is supported for scheduling direct\nmessages, clients are encouraged to use to the modern convention of\n`\"direct\"` to indicate this message type, because support for\n`\"private\"` may eventually be removed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate the type of a channel\nmessage.\n", - "type": "string", - "enum": ["direct", "channel", "stream", "private"], - "example": "stream" - }, - "to": { - "description": "The scheduled message's tentative target audience.\n\nFor channel messages, the integer ID of the channel.\nFor direct messages, a list containing integer user IDs.\n\nRequired when updating the `type` of the scheduled message.\n", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "integer" - }, - "minLength": 1 - } - ], - "example": 11 - }, - "content": { - "description": "The updated content of the scheduled message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n", - "type": "string", - "example": "Hello" - }, - "topic": { - "description": "The updated topic of the scheduled message.\n\nRequired when updating the `type` of the scheduled message to\n`\"stream\"` or `\"channel\"`. Ignored when the existing or updated\n`type` of the scheduled message is `\"direct\"` (or `\"private\"`).\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", - "type": "string", - "example": "Castle" - }, - "scheduled_delivery_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message will be sent,\nin UTC seconds.\n\nRequired when updating a scheduled message that the server\nhas already tried and failed to send. This state is indicated\nwith `\"failed\": true` in `scheduled_messages` objects; see\nresponse description at\n[`GET /scheduled_messages`](/api/get-scheduled-messages#response).\n", - "example": 3165826990 - } - } - }, - "encoding": { - "to": { - "contentType": "application/json" - }, - "scheduled_delivery_timestamp": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {} - }, - "example": { - "result": "success", - "msg": "" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/NonExistingChannelIdError" - }, - { - "description": "A typical failed JSON response for when a channel message is scheduled\nto be sent to a channel that does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid user ID 10", - "result": "error" - }, - "description": "A typical failed JSON response for when a direct message is scheduled\nto be sent to a user that does not exist:\n" - } - ] - } - ] - } - } - } - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no scheduled message exists\nwith the provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Scheduled message does not exist" - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "delete-scheduled-message", - "tags": ["scheduled_messages"], - "summary": "Delete a scheduled message", - "description": "Delete, and therefore cancel sending, a previously [scheduled\nmessage](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n", - "parameters": [ - { - "name": "scheduled_message_id", - "in": "path", - "schema": { - "type": "integer" - }, - "description": "The ID of the scheduled message to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n", - "required": true, - "example": 1 - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when no scheduled message exists\nwith the provided ID:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Scheduled message does not exist" - } - } - ] - } - } - } - } - } - } - }, - "/default_streams": { - "post": { - "operationId": "add-default-stream", - "tags": ["channels"], - "summary": "Add a default channel", - "x-requires-administrator": true, - "description": "Add a channel to the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the target channel.\n", - "type": "integer", - "example": 10 - } - }, - "required": ["stream_id"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "A typical failed JSON response for when an invalid channel ID is passed:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Private channels cannot be made default.", - "result": "error" - }, - "description": "A typical failed JSON response for when a user tries to add a private channel\nto the default channels set:\n" - } - ] - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "remove-default-stream", - "summary": "Remove a default channel", - "tags": ["channels"], - "description": "Remove a channel from the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", - "x-requires-administrator": true, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the target channel.\n", - "type": "integer", - "example": 10 - } - }, - "required": ["stream_id"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "A typical failed JSON response for when an invalid channel ID is passed:\n" - } - ] - } - } - } - } - } - } - }, - "/messages": { - "get": { - "operationId": "get-messages", - "summary": "Get messages", - "tags": ["messages"], - "description": "This endpoint is the primary way to fetch a messages. It is used by all official\nZulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as\nmany bots, API clients, backup scripts, etc.\n\nMost queries will specify a [narrow filter](/api/get-messages#parameter-narrow),\nto fetch the messages matching any supported [search\nquery](/help/search-for-messages). If not specified, it will return messages\ncorresponding to the user's [combined feed](/help/combined-feed). There are two\nways to specify which messages matching the narrow filter to fetch:\n\n- A range of messages, described by an `anchor` message ID (or a string-format\n specification of how the server should computer an anchor to use) and a maximum\n number of messages in each direction from that anchor.\n\n- A rarely used variant (`message_ids`) where the client specifies the message IDs\n to fetch.\n\nThe server returns the matching messages, sorted by message ID, as well as some\nmetadata that makes it easy for a client to determine whether there are more\nmessages matching the query that were not returned due to the `num_before` and\n`num_after` limits.\n\nNote that a user's message history does not contain messages sent to\nchannels before they [subscribe](/api/subscribe), and newly created\nbot users are not usually subscribed to any channels.\n\nWe recommend requesting at most 1000 messages in a batch, to avoid generating very\nlarge HTTP responses. A maximum of 5000 messages can be obtained per request;\nattempting to exceed this will result in an error.\n\n**Changes**: The `message_ids` option is new in Zulip 10.0 (feature level 300).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": [ - "client_gravatar", - "apply_markdown", - "use_first_unread_anchor", - "include_anchor", - "message_ids" - ] - } - } - ] - }, - "parameters": [ - { - "name": "anchor", - "in": "query", - "description": "Integer message ID to anchor fetching of new messages. Supports special\nstring values for when the client wants the server to compute the anchor\nto use:\n\n- `newest`: The most recent message.\n- `oldest`: The oldest message.\n- `first_unread`: The oldest unread message matching the\n query, if any; otherwise, the most recent message.\n\n**Changes**: String values are new in Zulip 3.0 (feature level 1). The\n`first_unread` functionality was supported in Zulip 2.1.x\nand older by not sending `anchor` and using `use_first_unread_anchor`.\n\nIn Zulip 2.1.x and older, `oldest` can be emulated with\n`\"anchor\": 0`, and `newest` with `\"anchor\": 10000000000000000`\n(that specific large value works around a bug in Zulip\n2.1.x and older in the `found_newest` return value).\n", - "schema": { - "$ref": "#/components/schemas/Anchor" - }, - "example": "43" - }, - { - "name": "include_anchor", - "in": "query", - "description": "Whether a message with the specified ID matching the narrow\nshould be included.\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - { - "name": "num_before", - "in": "query", - "description": "The number of messages with IDs less than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n", - "schema": { - "type": "integer", - "minimum": 0 - }, - "example": 4, - "required": false - }, - { - "name": "num_after", - "in": "query", - "description": "The number of messages with IDs greater than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n", - "schema": { - "type": "integer", - "minimum": 0 - }, - "example": 8, - "required": false - }, - { - "name": "narrow", - "in": "query", - "description": "The narrow where you want to fetch the messages from. See how to\n[construct a narrow](/api/construct-narrow).\n\nNote that many narrows, including all that lack a `channel`, `channels`,\n`stream`, or `streams` operator, search the user's personal message\nhistory. See [searching shared\nhistory](/help/search-for-messages#search-shared-history)\nfor details.\n\nFor example, if you would like to fetch messages from all public channels instead\nof only the user's message history, then a specific narrow for\nmessages sent to all public channels can be used:\n`{\"operator\": \"channels\", \"operand\": \"public\"}`.\n\nNewly created bot users are not usually subscribed to any\nchannels, so bots using this API should either be\nsubscribed to appropriate channels or use a shared history\nsearch narrow with this endpoint.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "object", - "required": ["operator", "operand"], - "additionalProperties": false, - "properties": { - "operator": { - "type": "string" - }, - "operand": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "integer" - } - } - ] - }, - "negated": { - "type": "boolean" - } - } - }, - { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 2, - "maxItems": 2 - } - ] - }, - "default": [] - }, - "example": [ - { - "operand": "Denmark", - "operator": "channel" - } - ] - } - } - }, - { - "$ref": "#/components/parameters/ClientGravatar" - }, - { - "name": "apply_markdown", - "in": "query", - "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\nMarkdown-format text that user entered.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - { - "name": "use_first_unread_anchor", - "in": "query", - "deprecated": true, - "description": "Legacy way to specify `\"anchor\": \"first_unread\"` in Zulip 2.1.x and older.\n\nWhether to use the (computed by the server) first unread message\nmatching the narrow as the `anchor`. Mutually exclusive with `anchor`.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by\n`\"anchor\": \"first_unread\"`.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - { - "name": "message_ids", - "in": "query", - "description": "A list of message IDs to fetch. The server will return messages corresponding to the\nsubset of the requested message IDs that exist and the current user has access to,\npotentially filtered by the narrow (if that parameter is provided).\n\nIt is an error to pass this parameter as well as any of the parameters involved in\nspecifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`,\n`num_before`, and `num_after`.\n\n**Changes**: New in Zulip 10.0 (feature level 300). Previously, there was\nno way to request a specific set of messages IDs.\n", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "integer" - } - }, - "example": [1, 2, 3] - } - } - }, - { - "name": "allow_empty_topic_name", - "in": "query", - "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": ["result", "msg", "messages"], - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "anchor": { - "type": "integer", - "description": "The same `anchor` specified in the request (or the computed one, if\n`use_first_unread_anchor` is `true`).\n\nOnly present if `message_ids` is not provided.\n" - }, - "found_newest": { - "type": "boolean", - "description": "Whether the server promises that the `messages` list includes the very\nnewest messages matching the narrow (used by clients that paginate their\nrequests to decide whether there may be more messages to fetch).\n" - }, - "found_oldest": { - "type": "boolean", - "description": "Whether the server promises that the `messages` list includes the very\noldest messages matching the narrow (used by clients that paginate their\nrequests to decide whether there may be more messages to fetch).\n" - }, - "found_anchor": { - "type": "boolean", - "description": "Whether the anchor message is included in the\nresponse. If the message with the ID specified\nin the request does not exist, did not match\nthe narrow, or was excluded via\n`\"include_anchor\": false`, this will be false.\n" - }, - "history_limited": { - "type": "boolean", - "description": "Whether the message history was limited due to\nplan restrictions. This flag is set to `true`\nonly when the oldest messages(`found_oldest`)\nmatching the narrow is fetched.\n" - }, - "messages": { - "type": "array", - "description": "An array of `message` objects.\n\n**Changes**: In Zulip 3.1 (feature level 26), the\n`sender_short_name` field was removed from message\nobjects.\n", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/MessagesBase" - }, - { - "additionalProperties": false, - "properties": { - "avatar_url": { - "nullable": true - }, - "client": {}, - "content": {}, - "content_type": {}, - "display_recipient": {}, - "edit_history": {}, - "id": {}, - "is_me_message": {}, - "last_edit_timestamp": {}, - "last_moved_timestamp": {}, - "reactions": {}, - "recipient_id": {}, - "sender_email": {}, - "sender_full_name": {}, - "sender_id": {}, - "sender_realm_str": {}, - "stream_id": {}, - "subject": {}, - "submessages": {}, - "timestamp": {}, - "topic_links": {}, - "type": {}, - "flags": { - "type": "array", - "description": "The user's [message flags][message-flags] for the message.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", - "items": { - "type": "string" - } - }, - "match_content": { - "type": "string", - "description": "Only present if keyword search was included among the narrow parameters.\n\nHTML content of a queried message that matches the narrow, with\n`` elements wrapping the matches for the\nsearch keywords.\n" - }, - "match_subject": { - "type": "string", - "description": "Only present if keyword search was included among the narrow parameters.\n\nHTML-escaped topic of a queried message that matches the narrow, with\n`` elements wrapping the matches for the\nsearch keywords.\n" - } - } - } - ] - } - } - }, - "example": { - "anchor": 21, - "found_newest": true, - "found_anchor": true, - "result": "success", - "msg": "", - "messages": [ - { - "subject": "", - "sender_realm_str": "zulip", - "type": "private", - "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", - "flags": ["read"], - "id": 16, - "display_recipient": [ - { - "id": 4, - "is_mirror_dummy": false, - "email": "hamlet@zulip.com", - "full_name": "King Hamlet" - }, - { - "id": 5, - "is_mirror_dummy": false, - "email": "iago@zulip.com", - "full_name": "Iago" - }, - { - "id": 8, - "is_mirror_dummy": false, - "email": "prospero@zulip.com", - "full_name": "Prospero from The Tempest" - } - ], - "content_type": "text/html", - "is_me_message": false, - "timestamp": 1527921326, - "sender_id": 4, - "sender_full_name": "King Hamlet", - "recipient_id": 27, - "topic_links": [], - "client": "ZulipDataImport", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "submessages": [], - "sender_email": "hamlet@zulip.com", - "reactions": [] - }, - { - "subject": "Verona3", - "stream_id": 5, - "sender_realm_str": "zulip", - "type": "stream", - "content": "

Wait, is this from the frontend js code or backend python code

", - "flags": ["read"], - "id": 21, - "display_recipient": "Verona", - "content_type": "text/html", - "is_me_message": false, - "timestamp": 1527939746, - "sender_id": 4, - "sender_full_name": "King Hamlet", - "recipient_id": 20, - "topic_links": [], - "client": "ZulipDataImport", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "submessages": [], - "sender_email": "hamlet@zulip.com", - "reactions": [] - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "send-message", - "summary": "Send a message", - "tags": ["messages"], - "description": "Send a [channel message](/help/introduction-to-topics) or a\n[direct message](/help/direct-messages).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "type": { - "description": "The type of message to be sent.\n\n`\"direct\"` for a direct message and `\"stream\"` or `\"channel\"` for a\nchannel message.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to request a channel message.\n\nIn Zulip 7.0 (feature level 174), `\"direct\"` was added as\nthe preferred way to request a direct message, deprecating the original\n`\"private\"`. While `\"private\"` is still supported for requesting direct\nmessages, clients are encouraged to use to the modern convention with\nservers that support it, because support for `\"private\"` will eventually\nbe removed.\n", - "type": "string", - "enum": ["direct", "channel", "stream", "private"], - "example": "direct" - }, - "to": { - "description": "For channel messages, either the name or integer ID of the channel. For\ndirect messages, either a list containing integer user IDs or a list\ncontaining string Zulip API email addresses.\n\n**Changes**: Support for using user/channel IDs was added in Zulip 2.0.0.\n", - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "string" - } - }, - { - "type": "array", - "items": { - "type": "integer" - }, - "minLength": 1 - } - ], - "example": [9, 10] - }, - "content": { - "$ref": "#/components/schemas/RequiredContent" - }, - "topic": { - "description": "The topic of the message. Only required for channel messages\n(`\"type\": \"stream\"` or `\"type\": \"channel\"`), ignored otherwise.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\n**Changes**: Before Zulip 10.0 (feature level 370), `\"(no topic)\"`\nwas not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 2.0.0. Previous Zulip releases encoded\nthis as `subject`, which is currently a deprecated alias.\n", - "type": "string", - "example": "Castle" - }, - "queue_id": { - "type": "string", - "description": "For clients supporting\n[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),\nthe [event queue](/api/register-queue)\nID for the client. If passed, `local_id` is required. If the message is\nsuccessfully sent, the server will include `local_id` in the `message` event\nthat the client with this `queue_id` will receive notifying it of the new message\nvia [`GET /events`](/api/get-events). This lets the client know unambiguously\nthat it should replace the locally echoed message, rather than adding this new\nmessage (which would be correct if the user had sent the new message from another\ndevice).\n", - "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8" - }, - "local_id": { - "type": "string", - "description": "For clients supporting local echo, a unique string-format identifier\nchosen freely by the client; the server will pass it back to the client without\ninspecting it, as described in the `queue_id` description.\n", - "example": "100.01" - }, - "read_by_sender": { - "type": "boolean", - "description": "Whether the message should be initially marked read by its\nsender. If unspecified, the server uses a heuristic based\non the client name.\n\n**Changes**: New in Zulip 8.0 (feature level 236).\n", - "example": true - } - }, - "required": ["type", "to", "content"] - }, - "encoding": { - "to": { - "contentType": "application/json" - }, - "read_by_sender": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": ["id"], - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The unique ID assigned to the sent message.\n" - }, - "automatic_new_visibility_policy": { - "type": "integer", - "enum": [2, 3], - "description": "If the message's sender had configured their [visibility policy settings](/help/mute-a-topic)\nto potentially automatically follow or unmute topics when sending messages,\nand one of these policies did in fact change the user's visibility policy\nfor the topic where this message was sent, the new value for that user's\nvisibility policy for the recipient topic.\n\nOnly present if the sender's visibility was in fact changed.\n\nThe value can be either [unmuted or followed](/api/update-user-topic#parameter-visibility_policy).\n\nClients will also be notified about the change in policy via a\n`user_topic` event as usual. This field is intended to be used by clients\nto explicitly inform the user when a topic's visibility policy was changed\nautomatically due to sending a message.\n\nFor example, the Zulip web application uses this field to decide whether\nto display a warning or notice suggesting to unmute the topic after\nsending a message to a muted channel. Such a notice would be confusing in\nthe event that the act of sending the message had already resulted in the\nuser automatically unmuting or following the topic in question.\n\n**Changes**: New in Zulip 8.0 (feature level 218).\n" - } - }, - "example": { - "msg": "", - "id": 42, - "automatic_new_visibility_policy": 2, - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/NonExistingChannelNameError" - }, - { - "description": "A typical failed JSON response for when a channel message is sent to a channel\nthat does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid email 'eeshan@zulip.com'", - "result": "error" - }, - "description": "A typical failed JSON response for when a direct message is sent to a user\nthat does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "You do not have permission to use channel wildcard mentions in this channel.", - "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED" - }, - "description": "An example JSON error response for when the message was rejected because\nthe message contains a stream wildcard mention, but the user doesn't have\npermission to use such a mention in this channel as the user is not present\nin `can_mention_many_users_group` and the channel contains a large number\nof subscribers.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "You do not have permission to use topic wildcard mentions in this topic.", - "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED" - }, - "description": "An example JSON error response for when the message was rejected because\nthe message contains a topic wildcard mention, but the user doesn't have\npermission to use such a mention in this topic as the user is not present\nin `can_mention_many_users_group` and the topic contains a large number\nof participants.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously,\n`wildcard_mention_policy` was not enforced for topic mentions.\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}/history": { - "get": { - "operationId": "get-message-history", - "summary": "Get a message's edit history", - "tags": ["messages"], - "description": "Fetch the message edit history of a previously edited message.\n\nNote that edit history may be disabled in some organizations; see the\n[Zulip help center documentation on editing messages][edit-settings].\n\n[edit-settings]: /help/view-a-messages-edit-history\n", - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - }, - { - "name": "allow_empty_topic_name", - "in": "query", - "description": "Whether the topic names i.e. `topic` and `prev_topic` fields in\nthe `message_history` objects returned can be empty string.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334).\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "x-response-description": "Please note that the original message's snapshot only contains the fields\n`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This\nsnapshot will be the only one present if the message has never been edited.\n\nAlso note that each snapshot object will only contain additional data for the\nmodified fields for that particular edit (e.g. if only the topic or channel\nwas edited, `prev_content`, `prev_rendered_content`, and\n`content_html_diff` will not appear).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "message_history": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "topic": { - "type": "string", - "description": "The topic of the message immediately\nafter this edit event.\n" - }, - "prev_topic": { - "type": "string", - "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately\nprior to this edit event.\n" - }, - "stream": { - "type": "integer", - "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message\nimmediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" - }, - "prev_stream": { - "type": "integer", - "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message immediately\nprior to this edit event.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n" - }, - "content": { - "type": "string", - "description": "The raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) content of the message\nimmediately after this edit event.\n" - }, - "rendered_content": { - "type": "string", - "description": "The rendered HTML representation of `content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "prev_content": { - "type": "string", - "description": "Only present if message's content was edited.\n\nThe raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) content of the message immediately\nprior to this edit event.\n" - }, - "prev_rendered_content": { - "type": "string", - "description": "Only present if message's content was edited.\n\nThe rendered HTML representation of `prev_content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "user_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user that made the edit.\n\nWill be `null` only for edit history\nevents predating March 2017.\n\nClients can display edit history events where this\nis `null` as modified by either the sender (for content\nedits) or an unknown user (for topic edits).\n" - }, - "content_html_diff": { - "type": "string", - "description": "Only present if message's content was edited.\n\nAn HTML diff between this version of the message\nand the previous one.\n" - }, - "timestamp": { - "type": "integer", - "description": "The UNIX timestamp for this edit.\n" - } - } - }, - "description": "A chronologically sorted, oldest to newest, array\nof `snapshot` objects, each one with the values of\nthe message after the edit.\n" - } - }, - "example": { - "message_history": [ - { - "content": "Hello!", - "topic": "party at my houz", - "rendered_content": "

Hello!

", - "timestamp": 1530129122, - "user_id": 5 - }, - { - "topic": "party at my house", - "content": "Howdy!", - "prev_content": "Hello!", - "rendered_content": "

Howdy!

", - "user_id": 5, - "prev_rendered_content": "

Hello!

", - "content_html_diff": "

Howdy!

Hello!

", - "prev_topic": "party at my houz", - "timestamp": 1530129134 - } - ], - "msg": "", - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidMessageError" - }, - { - "description": "An example JSON response for when the specified message does not exist:\n" - } - ] - } - } - } - } - } - } - }, - "/messages/flags": { - "post": { - "operationId": "update-message-flags", - "summary": "Update personal message flags", - "tags": ["messages"], - "description": "Add or remove personal message flags like `read` and `starred`\non a collection of message IDs.\n\nSee also the endpoint for [updating flags on a range of\nmessages within a narrow](/api/update-message-flags-for-narrow).\n", - "x-parameter-description": "## Available flags\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FlagPurpose
read\n Whether the user has read the message. Messages\n start out unread (except for messages the user\n themself sent using a non-API client) and can\n later be marked as read.\n
starredWhether the user has starred this message.
collapsedWhether the user has collapsed this message.
mentioned\n Whether the current user\n was mentioned\n by this message, either directly or via a user\n group. Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n a mention of the current user.\n
stream_wildcard_mentioned\n Whether this message contained a\n channel wildcard mention\n (like @**all**). Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n a channel wildcard mention.\n

\n Changes: New in Zulip 8.0 (feature level 224).\n
topic_wildcard_mentioned\n Whether this message contained a\n topic wildcard mention\n (@**topic**).\n Cannot be changed by the user directly, but can change if\n the message is edited to add/remove a topic wildcard mention.\n

\n Changes: New in Zulip 8.0 (feature level 224).\n
has_alert_word\n Whether the message contains any of the current user's\n configured alert words.\n Cannot be changed by the user directly, but\n can change if the message is edited to add/remove\n one of the current user's alert words.\n
historical\n Is true for messages that the user did not receive\n at the time they were sent but later was added to\n the user's history (e.g. because they starred or\n reacted to a message sent to a public channel\n before they subscribed to that channel). Cannot be\n changed by the user directly.\n
wildcard_mentioned\n Whether this message contained either a\n channel wildcard mention\n (like @**all**) or a\n topic wildcard mention\n (@**topic**). Cannot be changed by the user directly, but can change if\n the message is edited to add/remove a channel and/or topic wildcard\n mention.\n

\n Changes: Deprecated in Zulip 8.0 (feature level 224), in favor of\n the stream_wildcard_mentioned and\n topic_wildcard_mentioned flags. The\n wildcard_mentioned flag exists for backwards compatibility\n with older clients and equals\n stream_wildcard_mentioned || topic_wildcard_mentioned.\n Clients supporting older server versions should treat this field as a\n previous name for the stream_wildcard_mentioned flag as\n topic wildcard mentions were not available prior to this feature level.\n
\n
\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "messages": { - "description": "An array containing the IDs of the target messages.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [4, 8, 15] - }, - "op": { - "description": "Whether to `add` the flag or `remove` it.\n", - "type": "string", - "enum": ["add", "remove"], - "example": "add" - }, - "flag": { - "description": "The flag that should be added/removed.\n", - "type": "string", - "example": "read" - } - }, - "required": ["messages", "op", "flag"] - }, - "encoding": { - "messages": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "messages": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "An array with the IDs of the modified messages.\n" - }, - "ignored_because_not_subscribed_channels": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Only present if the flag is `read` and the operation is `remove`.\n\nZulip has an invariant that all unread messages must be in channels\nthe user is subscribed to. This field will contain a list of the\nchannels whose messages were skipped to mark as unread because the\nuser is not subscribed to them.\n\n**Changes**: New in Zulip 10.0 (feature level 355).\n" - } - }, - "example": { - "msg": "", - "messages": [4, 18, 15], - "ignored_because_not_subscribed_channels": [12, 13, 9], - "result": "success" - } - } - ] - } - } - } - } - } - } - }, - "/messages/flags/narrow": { - "post": { - "operationId": "update-message-flags-for-narrow", - "summary": "Update personal message flags for narrow", - "tags": ["messages"], - "description": "Add or remove personal message flags like `read` and `starred`\non a range of messages within a narrow.\n\nSee also [the endpoint for updating flags on specific message\nIDs](/api/update-message-flags).\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["include_anchor"] - } - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "anchor": { - "allOf": [ - { - "$ref": "#/components/schemas/Anchor" - }, - { - "description": "Integer message ID to anchor updating of flags. Supports special\nstring values for when the client wants the server to compute the anchor\nto use:\n\n- `newest`: The most recent message.\n- `oldest`: The oldest message.\n- `first_unread`: The oldest unread message matching the\n query, if any; otherwise, the most recent message.\n", - "example": "43" - } - ] - }, - "include_anchor": { - "description": "Whether a message with the specified ID matching the narrow\nshould be included in the update range.\n", - "type": "boolean", - "default": true, - "example": false - }, - "num_before": { - "description": "Limit the number of messages preceding the anchor in the\nupdate range. The server may decrease this to bound\ntransaction sizes.\n", - "type": "integer", - "minimum": 0, - "example": 4 - }, - "num_after": { - "description": "Limit the number of messages following the anchor in the\nupdate range. The server may decrease this to bound\ntransaction sizes.\n", - "type": "integer", - "minimum": 0, - "example": 8 - }, - "narrow": { - "description": "The narrow you want update flags within. See how to\n[construct a narrow](/api/construct-narrow).\n\nNote that, when adding the `read` flag to messages, clients should\nconsider including a narrow with the `is:unread` filter as an\noptimization. Including that filter takes advantage of the fact that\nthe server has a database index for unread messages.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", - "type": "array", - "items": { - "oneOf": [ - { - "type": "object", - "required": ["operator", "operand"], - "additionalProperties": false, - "properties": { - "operator": { - "type": "string" - }, - "operand": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "integer" - } - } - ] - }, - "negated": { - "type": "boolean" - } - } - }, - { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 2, - "maxItems": 2 - } - ] - }, - "default": [], - "example": [ - { - "operand": "Denmark", - "operator": "channel" - } - ] - }, - "op": { - "description": "Whether to `add` the flag or `remove` it.\n", - "type": "string", - "enum": ["add", "remove"], - "example": "add" - }, - "flag": { - "description": "The flag that should be added/removed. See [available\nflags](/api/update-message-flags#available-flags).\n", - "type": "string", - "example": "read" - } - }, - "required": [ - "anchor", - "num_before", - "num_after", - "narrow", - "op", - "flag" - ] - }, - "encoding": { - "include_anchor": { - "contentType": "application/json" - }, - "num_before": { - "contentType": "application/json" - }, - "num_after": { - "contentType": "application/json" - }, - "narrow": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": [ - "processed_count", - "updated_count", - "first_processed_id", - "last_processed_id", - "found_oldest", - "found_newest" - ], - "properties": { - "result": {}, - "msg": {}, - "processed_count": { - "type": "integer", - "description": "The number of messages that were within the\nupdate range (at most `num_before + 1 +\nnum_after`).\n" - }, - "updated_count": { - "type": "integer", - "description": "The number of messages where the flag's\nvalue was changed (at most\n`processed_count`).\n" - }, - "first_processed_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the oldest message within the\nupdate range, or `null` if the range was\nempty.\n" - }, - "last_processed_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the newest message within the\nupdate range, or `null` if the range was\nempty.\n" - }, - "found_oldest": { - "type": "boolean", - "description": "Whether the update range reached backward\nfar enough to include very oldest message\nmatching the narrow (used by clients doing a\nbulk update to decide whether to issue\nanother request anchored at\n`first_processed_id`).\n" - }, - "found_newest": { - "type": "boolean", - "description": "Whether the update range reached forward far\nenough to include very oldest message\nmatching the narrow (used by clients doing a\nbulk update to decide whether to issue\nanother request anchored at\n`last_processed_id`).\n" - }, - "ignored_because_not_subscribed_channels": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Only present if the flag is `read` and the operation is `remove`.\n\nZulip has an invariant that all unread messages must be in channels\nthe user is subscribed to. This field will contain a list of the\nchannels whose messages were skipped to mark as unread because the\nuser is not subscribed to them.\n\n**Changes**: New in Zulip 10.0 (feature level 355).\n" - } - }, - "example": { - "result": "success", - "msg": "", - "processed_count": 11, - "updated_count": 8, - "first_processed_id": 35, - "last_processed_id": 55, - "found_oldest": false, - "found_newest": true, - "ignored_because_not_subscribed_channels": [12, 13, 9] - } - } - ] - } - } - } - } - } - } - }, - "/messages/render": { - "post": { - "operationId": "render-message", - "summary": "Render a message", - "tags": ["messages"], - "description": "Render a message to HTML.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "content": { - "$ref": "#/components/schemas/RequiredContent" - } - }, - "required": ["content"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "rendered": { - "type": "string", - "description": "The rendered HTML.\n" - } - }, - "example": { - "msg": "", - "rendered": "

foo

", - "result": "success" - } - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}/reactions": { - "post": { - "operationId": "add-reaction", - "summary": "Add an emoji reaction", - "tags": ["messages"], - "description": "Add an [emoji reaction](/help/emoji-reactions) to a message.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["emoji_code", "reaction_type"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "emoji_name": { - "description": "The target emoji's human-readable name.\n\nTo find an emoji's name, hover over a message to reveal\nthree icons on the right, then click the smiley face icon.\nImages of available reaction emojis appear. Hover over the\nemoji you want, and note that emoji's text name.\n", - "type": "string", - "example": "octopus" - }, - "emoji_code": { - "$ref": "#/components/schemas/EmojiCode" - }, - "reaction_type": { - "$ref": "#/components/schemas/ReactionType" - } - }, - "required": ["emoji_name"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid emoji code", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response for when the emoji code is invalid:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Reaction already exists.", - "code": "REACTION_ALREADY_EXISTS" - }, - "description": "An example JSON error response for when the reaction already exists.\n\n**Changes**: New in Zulip 8.0 (feature level 193). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" - } - ] - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "remove-reaction", - "summary": "Remove an emoji reaction", - "tags": ["messages"], - "description": "Remove an [emoji reaction](/help/emoji-reactions) from a message.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["emoji_code", "reaction_type"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "emoji_name": { - "description": "The target emoji's human-readable name.\n\nTo find an emoji's name, hover over a message to reveal\nthree icons on the right, then click the smiley face icon.\nImages of available reaction emojis appear. Hover over the\nemoji you want, and note that emoji's text name.\n", - "type": "string", - "example": "octopus" - }, - "emoji_code": { - "$ref": "#/components/schemas/EmojiCode" - }, - "reaction_type": { - "$ref": "#/components/schemas/ReactionType" - } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid emoji code", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response for when the emoji code is invalid:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Reaction doesn't exist.", - "code": "REACTION_DOES_NOT_EXIST" - }, - "description": "An example JSON error response for when the reaction does not exist.\n\n**Changes**: New in Zulip 8.0 (feature level 193). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}/read_receipts": { - "get": { - "operationId": "get-read-receipts", - "summary": "Get a message's read receipts", - "tags": ["messages"], - "description": "Returns a list containing the IDs for all users who have\nmarked the message as read (and whose privacy settings allow\nsharing that information).\n\nThe list of users IDs will include any bots who have marked\nthe message as read via the API (providing a way for bots to\nindicate whether they have processed a message successfully in\na way that can be easily inspected in a Zulip client). Bots\nfor which this behavior is not desired may disable the\n`send_read_receipts` setting via the API.\n\nIt will never contain the message's sender.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n", - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "user_ids": { - "type": "array", - "description": "An array of IDs of users who have marked the target message as\nread and whose read status is available to the current user.\n\nThe IDs of users who have disabled sending read receipts\n(`\"send_read_receipts\": false`) will never appear in the response,\nnor will the message's sender. Additionally, the IDs of any users\nwho have been muted by the current user or who have muted the\ncurrent user will not be included in the response.\n\nThe current user's ID will appear if they have marked the target\nmessage as read.\n\n**Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of\nusers who have been muted by or have muted the current user were\nincluded in the response.\n", - "items": { - "type": "integer" - } - } - }, - "example": { - "msg": "", - "result": "success", - "user_ids": [3, 7, 9] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidMessageError" - }, - { - "description": "A typical JSON response when attempting to access read receipts for\na message ID that either does not exist or is not accessible to the\ncurrent user:\n" - } - ] - } - } - } - } - } - } - }, - "/messages/matches_narrow": { - "get": { - "operationId": "check-messages-match-narrow", - "summary": "Check if messages match a narrow", - "tags": ["messages"], - "description": "Check whether a set of messages match a [narrow](/api/construct-narrow).\n\nFor many common narrows (e.g. a topic), clients can write an efficient\nclient-side check to determine whether a newly arrived message belongs\nin the view.\n\nThis endpoint is designed to allow clients to handle more complex narrows\nfor which the client does not (or in the case of full-text search, cannot)\nimplement this check.\n\nThe format of the `match_subject` and `match_content` objects is designed\nto match those returned by the [`GET /messages`](/api/get-messages#response)\nendpoint, so that a client can splice these fields into a `message` object\nreceived from [`GET /events`](/api/get-events#message) and end up with an\nextended message object identical to how a [`GET /messages`](/api/get-messages)\nrequest for the current narrow would have returned the message.\n", - "parameters": [ - { - "name": "msg_ids", - "in": "query", - "description": "List of IDs for the messages to check.", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "integer" - } - }, - "example": [31, 32] - } - }, - "required": true - }, - { - "name": "narrow", - "in": "query", - "description": "A structure defining the narrow to check against. See how to\n[construct a narrow](/api/construct-narrow).\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object" - } - }, - "example": [ - { - "operator": "has", - "operand": "link" - } - ] - } - }, - "required": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "messages": { - "type": "object", - "description": "A dictionary with a key for each queried message that matches the narrow,\nwith message IDs as keys and search rendering data as values.\n", - "additionalProperties": { - "type": "object", - "additionalProperties": false, - "properties": { - "match_content": { - "type": "string", - "description": "HTML content of a queried message that matches the narrow. If the\nnarrow is a search narrow, `` elements\nwill be included, wrapping the matches for the search keywords.\n" - }, - "match_subject": { - "type": "string", - "description": "HTML-escaped topic of a queried message that matches the narrow. If the\nnarrow is a search narrow, `` elements\nwill be included wrapping the matches for the search keywords.\n" - } - }, - "description": "`message_id`: The ID of the message that matches the narrow. No record will be returned\nfor queried messages that do not match the narrow.\n" - } - } - }, - "example": { - "result": "success", - "msg": "", - "messages": { - "31": { - "match_content": "

http://foo.com

", - "match_subject": "test_topic" - } - } - } - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}": { - "get": { - "operationId": "get-message", - "summary": "Fetch a single message", - "tags": ["messages"], - "description": "Given a message ID, return the message object.\n\nAdditionally, a `raw_content` field is included. This field is\nuseful for clients that primarily work with HTML-rendered\nmessages but might need to occasionally fetch the message's\nraw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) (e.g. for [view\nsource](/help/view-the-markdown-source-of-a-message) or\nprefilling a message edit textarea).\n\n**Changes**: Before Zulip 5.0 (feature level 120), this\nendpoint only returned the `raw_content` field.\n", - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - }, - { - "name": "apply_markdown", - "in": "query", - "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\n[Zulip-flavored Markdown format](/help/format-your-message-using-markdown) text that user entered.\n\n**Changes**: New in Zulip 5.0 (feature level 120).\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - { - "name": "allow_empty_topic_name", - "in": "query", - "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "raw_content": { - "type": "string", - "deprecated": true, - "description": "The raw Markdown content of the message.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n\n**Deprecated** and to be removed once no longer required for\nlegacy clients. Modern clients should prefer passing\n`\"apply_markdown\": false` to request raw message content.\n" - }, - "message": { - "description": "An object containing details of the message.\n\n**Changes**: New in Zulip 5.0 (feature level 120).\n", - "allOf": [ - { - "$ref": "#/components/schemas/MessagesBase" - }, - { - "additionalProperties": false, - "properties": { - "avatar_url": { - "nullable": true - }, - "client": {}, - "content": {}, - "content_type": {}, - "display_recipient": {}, - "edit_history": {}, - "id": {}, - "is_me_message": {}, - "last_edit_timestamp": {}, - "last_moved_timestamp": {}, - "reactions": {}, - "recipient_id": {}, - "sender_email": {}, - "sender_full_name": {}, - "sender_id": {}, - "sender_realm_str": {}, - "stream_id": {}, - "subject": {}, - "submessages": {}, - "timestamp": {}, - "topic_links": {}, - "type": {}, - "flags": { - "type": "array", - "description": "The user's [message flags][message-flags] for the message.\n\n**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`\nflag was deprecated in favor of the `stream_wildcard_mentioned` and\n`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists\nfor backwards compatibility with older clients and equals\n`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients\nsupporting older server versions should treat this field as a previous\nname for the `stream_wildcard_mentioned` flag as topic wildcard mentions\nwere not available prior to this feature level.\n\n[message-flags]: /api/update-message-flags#available-flags\n", - "items": { - "type": "string" - } - } - } - } - ] - } - }, - "example": { - "raw_content": "**Don't** forget your towel!", - "result": "success", - "msg": "", - "message": { - "subject": "", - "sender_realm_str": "zulip", - "type": "private", - "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", - "flags": ["read"], - "id": 16, - "display_recipient": [ - { - "id": 4, - "is_mirror_dummy": false, - "email": "hamlet@zulip.com", - "full_name": "King Hamlet" - }, - { - "id": 5, - "is_mirror_dummy": false, - "email": "iago@zulip.com", - "full_name": "Iago" - }, - { - "id": 8, - "is_mirror_dummy": false, - "email": "prospero@zulip.com", - "full_name": "Prospero from The Tempest" - } - ], - "content_type": "text/html", - "is_me_message": false, - "timestamp": 1527921326, - "sender_id": 4, - "sender_full_name": "King Hamlet", - "recipient_id": 27, - "topic_links": [], - "client": "ZulipDataImport", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "submessages": [], - "sender_email": "hamlet@zulip.com", - "reactions": [] - } - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidMessageError" - }, - { - "description": "An example JSON response for when the specified message does not exist or it\nis not visible to the user making the query (e.g. it was a direct message\nbetween two other users):\n" - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "update-message", - "summary": "Edit a message", - "tags": ["messages"], - "description": "Update the content, topic, or channel of the message with the specified\nID.\n\nYou can [resolve topics](/help/resolve-a-topic) by editing the topic to\n`✔ {original_topic}` with the `propagate_mode` parameter set to\n`\"change_all\"`.\n\nSee [configuring message editing][config-message-editing] for detailed\ndocumentation on when users are allowed to edit message content, and\n[restricting moving messages][restrict-move-messages] for detailed\ndocumentation on when users are allowed to change a message's topic\nand/or channel.\n\nThe relevant realm settings in the API that are related to the above\nlinked documentation on when users are allowed to update messages are:\n\n- `allow_message_editing`\n- `can_resolve_topics_group`\n- `can_move_messages_between_channels_group`\n- `can_move_messages_between_topics_group`\n- `message_content_edit_limit_seconds`\n- `move_messages_within_stream_limit_seconds`\n- `move_messages_between_streams_limit_seconds`\n\nMore details about these realm settings can be found in the\n[`POST /register`](/api/register-queue) response or in the documentation\nof the [`realm op: update_dict`](/api/get-events#realm-update_dict)\nevent in [`GET /events`](/api/get-events).\n\n**Changes**: Prior to Zulip 10.0 (feature level 367), the permission for\nresolving a topic was managed by `can_move_messages_between_topics_group`.\nAs of this feature level, users belonging to the `can_resolve_topics_group`\nwill have the permission to [resolve topics](/help/resolve-a-topic) in the organization.\n\nIn Zulip 10.0 (feature level 316), `edit_topic_policy`\nwas removed and replaced by `can_move_messages_between_topics_group`\nrealm setting.\n\n**Changes**: In Zulip 10.0 (feature level 310), `move_messages_between_streams_policy`\nwas removed and replaced by `can_move_messages_between_channels_group`\nrealm setting.\n\nPrior to Zulip 7.0 (feature level 172), anyone could add a\ntopic to channel messages without a topic, regardless of the organization's\n[topic editing permissions](/help/restrict-moving-messages). As of this\nfeature level, messages without topics have the same restrictions for\ntopic edits as messages with topics.\n\nBefore Zulip 7.0 (feature level 172), by using the `change_all` value for\nthe `propagate_mode` parameter, users could move messages after the\norganization's configured time limits for changing a message's topic or\nchannel had passed. As of this feature level, the server will [return an\nerror](/api/update-message#response) with `\"code\":\n\"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED\"` if users, other than organization\nadministrators or moderators, try to move messages after these time\nlimits have passed.\n\nBefore Zulip 7.0 (feature level 162), users who were not administrators or\nmoderators could only edit topics if the target message was sent within the\nlast 3 days. As of this feature level, that time limit is now controlled by\nthe realm setting `move_messages_within_stream_limit_seconds`. Also at this\nfeature level, a similar time limit for moving messages between channels was\nadded, controlled by the realm setting\n`move_messages_between_streams_limit_seconds`. Previously, all users who\nhad permission to move messages between channels did not have any time limit\nrestrictions when doing so.\n\nBefore Zulip 7.0 (feature level 159), editing channels and topics of messages\nwas forbidden if the realm setting for `allow_message_editing` was `false`,\nregardless of an organization's configuration for the realm settings\n`edit_topic_policy` or `move_messages_between_streams_policy`.\n\nBefore Zulip 7.0 (feature level 159), message senders were allowed to edit\nthe topic of their messages indefinitely.\n\nIn Zulip 5.0 (feature level 75), the `edit_topic_policy` realm setting\nwas added, replacing the `allow_community_topic_editing` boolean.\n\nIn Zulip 4.0 (feature level 56), the `move_messages_between_streams_policy`\nrealm setting was added.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n[restrict-move-messages]: /help/restrict-moving-messages\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["stream_id"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "topic": { - "description": "The topic to move the message(s) to, to request changing the topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length\n\nShould only be sent when changing the topic, and will throw an error\nif the target message is not a channel message.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\nWhen [topics are required](/help/require-topics), this parameter can't\nbe `\"(no topic)\"`, an empty string, or the value of `realm_empty_topic_display_name`.\n\nYou can [resolve topics](/help/resolve-a-topic) by editing the topic to\n`✔ {original_topic}` with the `propagate_mode` parameter set to\n`\"change_all\"`. The empty string topic cannot be marked as resolved.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 2.0.0. Previous Zulip releases encoded this as `subject`,\nwhich is currently a deprecated alias.\n", - "type": "string", - "example": "Castle" - }, - "propagate_mode": { - "description": "Which message(s) should be edited:\n\n- `\"change_later\"`: The target message and all following messages.\n- `\"change_one\"`: Only the target message.\n- `\"change_all\"`: All messages in this topic.\n\nOnly the default value of `\"change_one\"` is valid when editing\nonly the content of a message.\n\nThis parameter determines both which messages get moved and also whether\nclients that are currently narrowed to the topic containing the message\nshould navigate or adjust their compose box recipient to point to the\npost-edit channel/topic.\n", - "type": "string", - "enum": ["change_one", "change_later", "change_all"], - "default": "change_one", - "example": "change_all" - }, - "send_notification_to_old_thread": { - "description": "Whether to send an automated message to the old topic to\nnotify users where the messages were moved to.\n\n**Changes**: Before Zulip 6.0 (feature level 152), this parameter\nhad a default of `true` and was ignored unless the channel was changed.\n\nNew in Zulip 3.0 (feature level 9).\n", - "type": "boolean", - "default": false, - "example": true - }, - "send_notification_to_new_thread": { - "description": "Whether to send an automated message to the new topic to\nnotify users where the messages came from.\n\nIf the move is just [resolving/unresolving a topic](/help/resolve-a-topic),\nthis parameter will not trigger an additional notification.\n\n**Changes**: Before Zulip 6.0 (feature level 152), this parameter\nwas ignored unless the channel was changed.\n\nNew in Zulip 3.0 (feature level 9).\n", - "type": "boolean", - "default": true, - "example": true - }, - "content": { - "$ref": "#/components/schemas/OptionalContent" - }, - "prev_content_sha256": { - "description": "An optional SHA-256 hash of the previous raw content of the message\nthat the client has at the time of the request.\n\nIf provided, the server will return an error if it does not match the\nSHA-256 hash of the message's content stored in the database.\n\nClients can use this feature to prevent races where multiple clients\nsave conflicting edits to a message.\n\n**Changes**: New in Zulip 11.0 (feature level 379).\n", - "type": "string", - "example": "6ae8a75555209fd6c44157c0aed8016e763ff435a19cf186f76863140143ff72" - }, - "stream_id": { - "description": "The channel ID to move the message(s) to, to request moving\nmessages to another channel.\n\nShould only be sent when changing the channel, and will throw an error\nif the target message is not a channel message.\n\nNote that a message's content and channel cannot be changed at the\nsame time, so sending both `content` and `stream_id` parameters will\nthrow an error.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", - "type": "integer", - "example": 43 - } - } - }, - "encoding": { - "send_notification_to_old_thread": { - "contentType": "application/json" - }, - "send_notification_to_new_thread": { - "contentType": "application/json" - }, - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "detached_uploads": { - "type": "array", - "description": "Details on all files uploaded by the acting user whose only references\nwere removed when editing this message. Clients should ask the acting user\nif they wish to delete the uploaded files returned in this response,\nwhich might otherwise remain visible only in message edit history.\n\nNote that [access to message edit history][edit-history-access]\nis configurable; this detail may be important in presenting the\nquestion clearly to users.\n\nNew in Zulip 10.0 (feature level 285).\n\n[edit-history-access]: /help/restrict-message-edit-history-access\n", - "items": { - "$ref": "#/components/schemas/Attachment" - } - } - }, - "example": { - "result": "success", - "msg": "", - "detached_uploads": [ - { - "id": 3, - "name": "1253601-1.jpg", - "path_id": "2/5d/BD5NRptFxPDKY3RUKwhhup8r/1253601-1.jpg", - "size": 1339060, - "create_time": 1687984706000, - "messages": [] - } - ] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "properties": { - "msg": { - "enum": [ - "Your organization has turned off message editing", - "You don't have permission to edit this message", - "The time limit for editing this message has past", - "Nothing to change", - "Topic can't be empty" - ] - } - }, - "example": { - "code": "BAD_REQUEST", - "msg": "You don't have permission to edit this message", - "result": "error" - }, - "description": "A typical JSON response for when one doesn't have the permission to\nedit a particular message:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED", - "first_message_id_allowed_to_move": 123, - "msg": "You only have permission to move the 2/5 most recent messages in this topic.", - "result": "error", - "total_messages_allowed_to_move": 2, - "total_messages_in_topic": 5 - }, - "description": "A special failed JSON response (`\"code\": \"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED\"`)\nfor when the user has permission to move\nthe target message, but asked to move all messages in a topic\n(`\"propagate_mode\": \"change_all\"`) and the user does not have permission\nto move the entire topic.\n\nThis happens when the topic contains some messages that are older than an\napplicable time limit for the requested topic move (see\n`move_messages_within_stream_limit_seconds` and/or\n`move_messages_between_streams_limit_seconds` in the\n[`POST /register`](/api/register-queue) response).\n\nThe error response contains data on which portion of this topic the user has\npermission to move. `first_message_id_allowed_to_move` is the oldest message\nID in this topic that the user has permission to move.\nThere are `total_messages_in_topic` in the topic, but the user only has\npermission to move the (most recent) `total_messages_allowed_to_move`\nmessages.\n\nClients should support this error code with\n`\"first_message_id_allowed_to_move\": null` for forward compatibility\nwith future server versions that may use this error code with other\npropagation modes where the user does not have permission to move any\nmessages, or where the server did not calculate the total message counts\nnoted above.\n\nClients can either only present the error to the user or, if\n`first_message_id_allowed_to_move` is not `null`, prompt the user to adjust\ntheir query with the above information.\n\nIf clients choose to present a prompt for this error code, they should\nrecommend the option of cancelling and (manually) asking a moderator to\nmove the entire topic, since that's often a better experience than\npartially moving a topic. This API supports a client that wishes to allow\nthe user to repeat the request with a `change_later` propagation mode and\na target message ID of `first_message_id_allowed_to_move`, if the user\ndesires to move only the portion of the topic that they can.\n\nNote that in a [private channel with protected history][private-channels],\nthe Zulip security model requires that the above calculations only include\nmessages the acting user has access to. So in the rare case of a user\nattempting to move a topic that started before the user joined a private\nchannel with protected history, this API endpoint might move only the portion\nof a topic that they have access to, without this error or any confirmation\ndialog.\n\n**Changes**: New in Zulip 7.0 (feature level 172).\n\n[private-channels]: /help/channel-permissions#private-channels\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "You do not have permission to use channel wildcard mentions in this channel.", - "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED" - }, - "description": "An example JSON error response for when the message was rejected because\nthe message contains a stream wildcard mention, but the user doesn't have\npermission to use such a mention in this channel as the user is not present\nin `can_mention_many_users_group` and the channel contains a large number\nof subscribers.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously, this\nerror returned the `\"BAD_REQUEST\"` code.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "You do not have permission to use topic wildcard mentions in this topic.", - "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED" - }, - "description": "An example JSON error response for when the message was rejected because\nthe message contains a topic wildcard mention, but the user doesn't have\npermission to use such a mention in this topic as the user is not present\nin `can_mention_many_users_group` and the topic contains a large number\nof participants.\n\n**Changes**: New in Zulip 8.0 (feature level 229). Previously,\n`wildcard_mention_policy` was not enforced for topic mentions.\n" - } - ] - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "delete-message", - "summary": "Delete a message", - "tags": ["messages"], - "description": "Permanently delete a message.\n\nThis API corresponds to the\n[delete a message completely][delete-completely] feature documented in\nthe Zulip help center.\n\n[delete-completely]: /help/delete-a-message#delete-a-message-completely\n", - "x-requires-administrator": true, - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidMessageError" - }, - { - "description": "An example JSON response for when the specified message does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "An example JSON response for when the user making the query does not\nhave permission to delete the message:\n", - "example": { - "code": "BAD_REQUEST", - "msg": "You don't have permission to delete this message", - "result": "error" - } - } - ] - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}/report": { - "post": { - "operationId": "report-message", - "summary": "Report a message", - "tags": ["messages"], - "description": "Sends a notification to the organization's moderation request channel,\nif it is configured, that reports the targeted message for review and\nmoderation.\n\nClients should check the `moderation_request_channel` realm setting to\ndecide whether to show the option to report messages in the UI.\n\nIf the `report_type` parameter value is `\"other\"`, the `description`\nparameter is required. Clients should also enforce and communicate this\nbehavior in the UI.\n\n**Changes**: New in Zulip 11.0 (feature level 382). This API builds on\nthe `moderation_request_channel` realm setting, which was added in\nfeature level 331.\n", - "parameters": [ - { - "$ref": "#/components/parameters/MessageId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "report_type": { - "description": "The reason that best describes why the current user is reporting the\ntarget message for moderation.\n", - "type": "string", - "enum": [ - "spam", - "harassment", - "inappropriate", - "norms", - "other" - ], - "example": "harassment" - }, - "description": { - "description": "A short description with additional context about why the current user\nis reporting the target message for moderation.\n\nClients should limit this string to a maximum length of 1000 characters.\n\nIf the `report_type` parameter is `\"other\"`, this parameter is required,\nand its value cannot be an empty string.\n", - "type": "string", - "example": "This message insults and mocks Frodo, which is against the code of conduct." - } - }, - "required": ["report_type"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Moderation request channel must be specified to enable message reporting.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response for when the organization's moderation\nrequest channel is not configured:\n" - } - ] - } - } - } - } - } - } - }, - "/user_uploads": { - "post": { - "operationId": "upload-file", - "summary": "Upload a file", - "tags": ["messages"], - "description": "[Upload](/help/share-and-upload-files) a single file and get the corresponding URL.\n\nInitially, only you will be able to access the link. To share the\nuploaded file, you'll need to [send a message][send-message]\ncontaining the resulting link. Users who can already access the link\ncan reshare it with other users by sending additional Zulip messages\ncontaining the link.\n\nThe maximum allowed file size is available in the `max_file_upload_size_mib`\nfield in the [`POST /register`](/api/register-queue) response. Note that\nlarge files (25MB+) may fail to upload using this API endpoint due to\nnetwork-layer timeouts, depending on the quality of your connection to the\nZulip server.\n\nFor uploading larger files, `/api/v1/tus` is an endpoint implementing the\n[`tus` resumable upload protocol](https://tus.io/protocols/resumable-upload),\nwhich supports uploading arbitrarily large files limited only by the server's\n`max_file_upload_size_mib` (Configured via `MAX_FILE_UPLOAD_SIZE` in\n`/etc/zulip/settings.py`). Clients which send authenticated credentials\n(either via browser-based cookies, or API key via `Authorization` header) may\nuse this endpoint to upload files.\n\n**Changes**: The `api/v1/tus` endpoint supporting resumable uploads was\nintroduced in Zulip 10.0 (feature level 296). Previously,\n`max_file_upload_size_mib` was typically 25MB.\n\n[uploaded-files]: /help/manage-your-uploaded-files\n[send-message]: /api/send-message\n", - "x-parameter-description": "As described above, the file to upload must be provided in the\nrequest's body.\n\n[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings\n", - "requestBody": { - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "filename": { - "type": "string", - "format": "binary", - "example": "/path/to/file" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "uri": { - "type": "string", - "deprecated": true, - "description": "The URL of the uploaded file. Alias of `url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 272). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" - }, - "url": { - "type": "string", - "description": "The URL of the uploaded file.\n\n**Changes**: New in Zulip 9.0 (feature level 272). Previously,\nthis property was only available under the legacy `uri` name.\n" - }, - "filename": { - "type": "string", - "description": "The filename that Zulip stored the upload as. This usually\ndiffers from the basename of the URL when HTML escaping is\nrequired to generate a valid URL.\n\nClients generating a Markdown link to a newly uploaded file\nshould do so by combining the `url` and `filename` fields in the\nresponse as follows: `[{filename}]({url})`, with care taken to\nclean `filename` of `[` and `]` characters that might break\nMarkdown rendering.\n\n**Changes**: New in Zulip 10.0 (feature level 285).\n" - } - }, - "example": { - "msg": "", - "result": "success", - "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", - "url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", - "filename": "zulip.txt" - } - } - ] - } - } - } - } - } - } - }, - "/user_uploads/{realm_id_str}/{filename}": { - "get": { - "operationId": "get-file-temporary-url", - "summary": "Get public temporary URL for an uploaded file", - "tags": ["messages"], - "description": "Get a temporary URL for access to an [uploaded file](/api/upload-file)\nthat doesn't require authentication.\n\nThe `SIGNED_ACCESS_TOKEN_VALIDITY_IN_SECONDS` server setting controls\nthe valid length of time for temporary access, which generally is set\nto a default of 60 seconds. Consumers of this API are expected to\nimmediately request the URL that it returns, and should not store it\nin any way.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", - "parameters": [ - { - "name": "realm_id_str", - "in": "path", - "description": "The ID of the Zulip organization.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - }, - { - "name": "filename", - "in": "path", - "description": "Path to the [uploaded file](/api/upload-file).\n", - "schema": { - "type": "string" - }, - "example": "4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", - "required": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "url": { - "type": "string", - "description": "A temporary URL that can be used to access the uploaded file\nwithout Zulip's normal API authentication.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55" - } - } - ] - } - } - } - } - } - } - }, - "/users": { - "get": { - "operationId": "get-users", - "summary": "Get users", - "tags": ["users"], - "description": "Retrieve details on users in the organization.\n\nBy default, returns all accessible users in the organization.\nThe `user_ids` query parameter can be used to limit the\nresults to a specific set of user IDs.\n\nOptionally includes values of [custom profile fields](/help/custom-profile-fields).\n\nYou can also [fetch details on a single user](/api/get-user).\n\n**Changes**: This endpoint did not support unauthenticated\naccess in organizations using the [public access\noption](/help/public-access-option) prior to Zulip 11.0\n(feature level 387).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": [""] - } - }, - { - "type": "exclude", - "parameters": { - "enum": [""] - }, - "description": "You may pass the `client_gravatar` query parameter as follows:\n" - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/ClientGravatar" - }, - { - "$ref": "#/components/parameters/IncludeCustomProfileFields" - }, - { - "name": "user_ids", - "in": "query", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "integer" - } - }, - "example": [1, 2, 3] - } - }, - "required": false, - "description": "Limits the results to the specified user IDs. If not\nprovided, the server will return all accessible users in\nthe organization.\n\n**Changes**: New in Zulip 11.0 (feature level 384).\n" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "members": { - "type": "array", - "description": "A list of `user` objects, each containing details about a user in the\norganization.\n", - "items": { - "$ref": "#/components/schemas/User" - } - } - }, - "example": { - "msg": "", - "result": "success", - "members": [ - { - "is_active": true, - "email": "AARON@zulip.com", - "delivery_email": null, - "is_admin": false, - "is_owner": false, - "role": 400, - "avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1", - "bot_type": null, - "timezone": "", - "is_bot": false, - "user_id": 7, - "profile_data": {}, - "is_guest": false, - "date_joined": "2019-10-20T07:50:53.728864+00:00", - "full_name": "aaron" - }, - { - "date_joined": "2019-10-20T07:50:53.729659+00:00", - "full_name": "King Hamlet", - "is_guest": false, - "profile_data": { - "4": { - "value": "0" - }, - "2": { - "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", - "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" - }, - "5": { - "value": "1900-01-01" - }, - "7": { - "value": "[11]" - }, - "6": { - "value": "https://blog.zulig.org" - }, - "1": { - "value": "+0-11-23-456-7890", - "rendered_value": "

+0-11-23-456-7890

" - }, - "8": { - "value": "zulipbot" - }, - "3": { - "rendered_value": "

Dark chocolate

", - "value": "Dark chocolate" - } - }, - "user_id": 10, - "is_bot": false, - "bot_type": null, - "timezone": "", - "is_admin": false, - "is_owner": false, - "role": 400, - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "is_active": true, - "email": "hamlet@zulip.com", - "delivery_email": null - }, - { - "bot_owner_id": 11, - "is_guest": false, - "date_joined": "2019-10-20T12:52:17.862053+00:00", - "full_name": "Iago's Bot", - "email": "iago-bot@zulipdev.com", - "delivery_email": "iago-bot@zulipdev.com", - "is_active": true, - "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", - "is_admin": false, - "is_owner": false, - "role": 400, - "user_id": 23, - "bot_type": 1, - "timezone": "", - "is_bot": true - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "create-user", - "summary": "Create a user", - "tags": ["users"], - "description": "Create a new user account via the API.\n\n!!! warn \"\"\n\n **Note**: On Zulip Cloud, this feature is available only for\n organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)\n or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators\n can request the required `can_create_users` permission for a bot or\n user by contacting [Zulip Cloud support][support] with an\n explanation for why it is needed. Self-hosted installations can\n toggle `can_create_users` on an account using the `manage.py\n change_user_role` [management command][management-commands].\n\n**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was\navailable to all organization administrators.\n\n[support]: /help/contact-support\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n", - "x-requires-administrator": true, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "email": { - "description": "The email address of the new user.\n", - "type": "string", - "example": "username@example.com" - }, - "password": { - "description": "The password of the new user.\n", - "type": "string", - "example": "abcd1234" - }, - "full_name": { - "description": "The full name of the new user.\n", - "type": "string", - "example": "New User" - } - }, - "required": ["email", "password", "full_name"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "user_id": { - "type": "integer", - "description": "The ID assigned to the newly created user.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" - } - }, - "example": { - "msg": "", - "result": "success", - "user_id": 25 - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Email is already in use.", - "result": "error" - }, - "description": "A typical JSON response for when another user with the same\nemail address already exists in the realm:\n" - } - ] - } - } - } - } - } - } - }, - "/users/{user_id}/reactivate": { - "post": { - "operationId": "reactivate-user", - "summary": "Reactivate a user", - "tags": ["users"], - "x-requires-administrator": true, - "description": "[Reactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/users/{user_id}/status": { - "post": { - "operationId": "update-status-for-user", - "summary": "Update user status", - "tags": ["users"], - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - } - ], - "description": "Administrator endpoint for changing the [status](/help/status-and-availability) of\nanother user.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n", - "x-requires-administrator": true, - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "status_text": { - "type": "string", - "description": "The text content of the status message. Sending the empty string\nwill clear the user's status.\n\n**Note**: The limit on the size of the message is 60 characters.\n", - "example": "on vacation" - }, - "emoji_name": { - "type": "string", - "description": "The name for the emoji to associate with this status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "car" - }, - "emoji_code": { - "type": "string", - "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "1f697" - }, - "reaction_type": { - "type": "string", - "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "unicode_emoji" - } - } - }, - "encoding": { - "away": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Insufficient permission", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response user making request does not have permission to update other user's status.:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Client did not pass any new values.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when no changes were requested:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "status_text is too long (limit: 60 characters)", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the\n`status_text` message exceeds the limit of\n60 characters:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when `emoji_name` is not specified\nbut `emoji_code` or `reaction_type` is specified:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Emoji 'invalid' does not exist", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the emoji name does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid emoji name.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the emoji name is invalid:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid custom emoji.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the custom emoji is invalid:\n" - } - ] - } - ] - } - } - } - } - } - }, - "get": { - "operationId": "get-user-status", - "summary": "Get a user's status", - "tags": ["users"], - "description": "Get the [status](/help/status-and-availability) currently set by a\nuser in the organization.\n\n**Changes**: New in Zulip 9.0 (feature level 262). Previously,\nuser statuses could only be fetched via the [`POST\n/register`](/api/register-queue) endpoint.\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "status": { - "allOf": [ - { - "description": "The status set by the user. Note that, if the user doesn't have a status\ncurrently set, then the returned dictionary will be empty as none of the\nkeys listed below will be present.\n" - }, - { - "$ref": "#/components/schemas/UserStatus" - } - ] - } - }, - "example": { - "result": "success", - "msg": "", - "status": { - "status_text": "on vacation", - "emoji_name": "car", - "emoji_code": "1f697", - "reaction_type": "unicode_emoji" - } - } - } - ] - } - } - } - }, - "400": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "No such user", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the user does not exist:\n" - } - ] - } - } - } - } - } - } - }, - "/users/{user_id_or_email}/presence": { - "get": { - "operationId": "get-user-presence", - "summary": "Get a user's presence", - "tags": ["users"], - "description": "Get the presence status for a specific user.\n\nThis endpoint is most useful for embedding data about a user's\npresence status in other sites (e.g. an employee directory). Full\nZulip clients like mobile/desktop apps will want to use the [main\npresence endpoint](/api/get-presence), which returns data for all\nactive users in the organization, instead.\n", - "parameters": [ - { - "name": "user_id_or_email", - "in": "path", - "description": "The ID or Zulip API email address of the user whose presence you want to fetch.\n\n**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported\nidentifying the user by Zulip API email.\n", - "schema": { - "type": "string" - }, - "example": "iago@zulip.com", - "required": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "presence": { - "type": "object", - "description": "An object containing the presence details for the user.\n", - "additionalProperties": { - "type": "object", - "additionalProperties": false, - "properties": { - "timestamp": { - "type": "integer", - "description": "When this update was received. If the timestamp\nis more than a few minutes in the past, the user is offline.\n" - }, - "status": { - "type": "string", - "description": "Whether the user had recently interacted with Zulip at the time\nof the timestamp.\n\nWill be either `\"active\"` or `\"idle\"`\n" - } - }, - "description": "`{client_name}` or `\"aggregated\"`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will always\ncontain two keys, `\"website\"` and `\"aggregated\"`, with identical data. The\nserver no longer stores which client submitted presence updates.\n\nPreviously, the `{client_name}` keys for these objects were the names of the\ndifferent clients where the user was logged in, for example `website` or\n`ZulipDesktop`.\n" - } - } - }, - "example": { - "presence": { - "website": { - "timestamp": 1532697622, - "status": "active" - }, - "aggregated": { - "timestamp": 1532697622, - "status": "active" - } - }, - "result": "success", - "msg": "" - } - } - ] - } - } - } - } - } - } - }, - "/users/me": { - "get": { - "operationId": "get-own-user", - "summary": "Get own user", - "tags": ["users"], - "description": "Get basic data about the user/bot that requests this endpoint.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was\nreplaced by the `can_manage_billing_group` realm setting.\n", - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "avatar_url": { - "type": "string", - "description": "URL for the requesting user's avatar.\n\n**Changes**: New in Zulip 2.1.0.\n", - "example": "x" - }, - "avatar_version": { - "type": "integer", - "description": "Version for the requesting user's avatar. Used for cache-busting requests\nfor the user's avatar. Clients generally shouldn't need to use this;\nmost avatar URLs sent by Zulip will already end with `?v={avatar_version}`.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", - "example": 1 - }, - "email": { - "type": "string", - "description": "Zulip API email of the requesting user.\n", - "example": "iago@zulip.com" - }, - "full_name": { - "type": "string", - "description": "Full name of the requesting user.\n", - "example": "Iago" - }, - "is_admin": { - "type": "boolean", - "description": "A boolean indicating if the requesting user is an admin.\n", - "example": true - }, - "is_owner": { - "type": "boolean", - "description": "A boolean indicating if the requesting user is\nan organization owner.\n\n**Changes**: New in Zulip 3.0 (feature level 8).\n", - "example": false - }, - "role": { - "type": "integer", - "enum": [100, 200, 300, 400, 600], - "description": "[Organization-level role](/api/roles-and-permissions) of\nthe requesting user.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" - }, - "is_guest": { - "type": "boolean", - "description": "A boolean indicating if the requesting user is a guest.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", - "example": false - }, - "is_bot": { - "type": "boolean", - "description": "A boolean indicating if the requesting user is a bot.\n", - "example": false - }, - "is_active": { - "type": "boolean", - "description": "A boolean specifying whether the requesting user account\nhas been deactivated.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", - "example": true - }, - "timezone": { - "type": "string", - "description": "The IANA identifier of the requesting user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", - "example": "" - }, - "date_joined": { - "type": "string", - "description": "The time the requesting user's account was created.\n\n**Changes**: New in Zulip 3.0 (feature level 10).\n", - "example": "2019-10-20T07:50:53.728864+00:00" - }, - "max_message_id": { - "type": "integer", - "deprecated": true, - "description": "The integer ID of the last message received by the requesting\nuser's account.\n\n**Deprecated**. We plan to remove this in favor of recommending\nusing `GET /messages` with `\"anchor\": \"newest\"`.\n", - "example": 30 - }, - "user_id": { - "type": "integer", - "description": "The user's ID.\n", - "example": 1 - }, - "delivery_email": { - "type": "string", - "description": "The requesting user's real email address.\n\n**Changes**: Prior to Zulip 7.0 (feature level 163), this field was\npresent only when `email_address_visibility` was restricted and the\nrequesting user had permission to access realm users' emails. As of\nthis feature level, this field is always present.\n" - }, - "profile_data": { - "$ref": "#/components/schemas/profile_data" - } - }, - "example": { - "avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1", - "avatar_version": 1, - "email": "iago@zulip.com", - "delivery_email": "iago@zulip.com", - "full_name": "Iago", - "is_admin": true, - "is_owner": false, - "role": 200, - "is_guest": false, - "is_bot": false, - "is_active": true, - "timezone": "", - "date_joined": "2019-10-20T07:50:53.728864+00:00", - "max_message_id": 30, - "msg": "", - "result": "success", - "user_id": 5, - "profile_data": { - "5": { - "value": "2000-01-01" - }, - "4": { - "value": "emacs" - }, - "7": { - "value": "[10]" - }, - "1": { - "value": "+1-234-567-8901", - "rendered_value": "

+1-234-567-8901

" - }, - "2": { - "rendered_value": "

Betrayer of Othello.

", - "value": "Betrayer of Othello." - }, - "8": { - "value": "zulip" - }, - "3": { - "value": "Apples", - "rendered_value": "

Apples

" - }, - "6": { - "value": "https://zulip.readthedocs.io/en/latest/" - } - } - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "deactivate-own-user", - "summary": "Deactivate own user", - "tags": ["users"], - "description": "Deactivates the current user's account. See also the administrative endpoint for\n[deactivating another user](/api/deactivate-user).\n\nThis endpoint is primarily useful to Zulip clients providing a user settings UI.\n", - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "entity": { - "type": "string", - "description": "An internationalized string that notes if the current user is the only\norganization owner or the only user in the organization.\n" - }, - "is_last_owner": { - "type": "boolean", - "description": "Whether the current user is the only organization owner (meaning there\nare other active users in the organization) or the only active user in the\norganization.\n" - } - }, - "required": ["entity", "is_last_owner"], - "example": { - "code": "CANNOT_DEACTIVATE_LAST_USER", - "msg": "Cannot deactivate the only organization owner", - "result": "error", - "entity": "organization owner", - "is_last_owner": true - }, - "description": "If the current user is the only organization owner or only user in the\norganization, their account cannot be deactivated and an error response\nwill be returned. The `is_last_owner` field in the error response\nindicates whether the user is the only owner (`true`) or the only user\n(`false`). The `entity` field in the error response is a internationalized\nstring that notes if the current user is the only organization owner or\nthe only user.\n\nAn example JSON error response when the current user is the only\norganization owner in the organization:\n" - } - ] - } - } - } - } - } - } - }, - "/users/me/alert_words": { - "get": { - "operationId": "get-alert-words", - "summary": "Get all alert words", - "tags": ["users"], - "description": "Get all of the user's configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "alert_words": { - "type": "array", - "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", - "items": { - "type": "string" - } - } - }, - "example": { - "result": "success", - "msg": "", - "alert_words": ["natural", "illustrious"] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "add-alert-words", - "summary": "Add alert words", - "tags": ["users"], - "description": "Add words (or phrases) to the user's set of configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "alert_words": { - "description": "An array of strings to be added to the user's set of configured\nalert words. Strings already present in the user's set of alert words\nalready are ignored.\n\nAlert words are case insensitive.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["foo", "bar"] - } - }, - "required": ["alert_words"] - }, - "encoding": { - "alert_words": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "alert_words": { - "type": "array", - "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", - "items": { - "type": "string" - } - } - }, - "example": { - "result": "success", - "msg": "", - "alert_words": ["foo", "bar", "natural", "illustrious"] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "alert_words[0] is too long (limit: 100 characters)", - "result": "error" - }, - "description": "An example JSON response for when a supplied alert word (or phrase)\nexceeds the character limit:\n" - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "remove-alert-words", - "summary": "Remove alert words", - "tags": ["users"], - "description": "Remove words (or phrases) from the user's set of configured [alert words][alert-words].\n\nAlert words are case insensitive.\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "alert_words": { - "description": "An array of strings to be removed from the user's set of configured\nalert words. Strings that are not in the user's set of alert words\nare ignored.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["foo"] - } - }, - "required": ["alert_words"] - }, - "encoding": { - "alert_words": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "alert_words": { - "type": "array", - "description": "An array of strings, where each string is an alert word (or phrase)\nconfigured by the user.\n", - "items": { - "type": "string" - } - } - }, - "example": { - "result": "success", - "msg": "", - "alert_words": ["bar", "natural", "illustrious"] - } - } - ] - } - } - } - } - } - } - }, - "/users/me/presence": { - "post": { - "operationId": "update-presence", - "summary": "Update your presence", - "tags": ["users"], - "description": "Update the current user's [presence][availability] and fetch presence data\nof other users in the organization.\n\nThis endpoint is meant to be used by clients for both:\n\n- Reporting the current user's presence status (`\"active\"` or `\"idle\"`)\n to the server.\n\n- Obtaining the presence data of all other users in the organization via\n regular polling.\n\nAccurate user presence is one of the most expensive parts of any\nchat application (in terms of bandwidth and other resources). Therefore,\nit is important that clients implementing Zulip's user presence system\nuse the modern [`last_update_id`](#parameter-last_update_id) protocol to\nminimize fetching duplicate user presence data.\n\nClient apps implementing presence are recommended to also consume [`presence`\nevents](/api/get-events#presence)), in order to learn about newly online users\nimmediately.\n\nThe Zulip server is responsible for implementing [invisible mode][invisible],\nwhich disables sharing a user's presence data. Nonetheless, clients\nshould check the `presence_enabled` field in user objects in order to\ndisplay the current user as online or offline based on whether they are\nsharing their presence information.\n\n**Changes**: As of Zulip 8.0 (feature level 228), if the\n`CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is\n`true`, then user presence data in the response is [limited to users\nthe current user can see/access][limit-visibility].\n\n[limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users\n[invisible]: /help/status-and-availability#invisible-mode\n[availability]: /help/status-and-availability#availability\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "last_update_id": { - "type": "integer", - "description": "The identifier that specifies what presence data the client already\nhas received, which allows the server to only return more recent\nuser presence data.\n\nThis should be set to `-1` during initialization of the client in\norder to fetch all user presence data, unless the client is obtaining\ninitial user presence metadata from the\n[`POST /register`](/api/register-queue) endpoint.\n\nIn subsequent queries to this endpoint, this value should be set to the\nmost recent value of `presence_last_update_id` returned by the server\nin this endpoint's response, which implements incremental fetching\nof user presence data.\n\nWhen this parameter is passed, the user presence data in the response\nwill always be in the modern format.\n\n**Changes**: New in Zulip 9.0 (feature level 263). Previously, the\nserver sent user presence data for all users who had been active in the\nlast two weeks unconditionally.\n", - "example": 5 - }, - "history_limit_days": { - "type": "integer", - "description": "Limits how far back in time to fetch user presence data. If not specified,\ndefaults to 14 days. A value of N means that the oldest presence data\nfetched will be from at most N days ago.\n\nNote that this is only useful during the initial user presence data fetch,\nas subsequent fetches should use the `last_update_id` parameter, which\nwill act as the limit on how much presence data is returned. `history_limit_days`\nis ignored if `last_update_id` is passed with a value greater than `0`,\nindicating that the client already has some presence data.\n\n**Changes**: New in Zulip 10.0 (feature level 288).\n", - "example": 365 - }, - "new_user_input": { - "type": "boolean", - "description": "Whether the user has interacted with the client (e.g. moved the mouse,\nused the keyboard, etc.) since the previous presence request from this\nclient.\n\nThe server uses data from this parameter to implement certain [usage\nstatistics](/help/analytics).\n\nUser interface clients that might run in the background, without the\nuser ever interacting with them, should be careful to only pass `true`\nif the user has actually interacted with the client in order to avoid\ncorrupting usage statistics graphs.\n", - "example": false, - "default": false - }, - "ping_only": { - "type": "boolean", - "description": "Whether the client is sending a ping-only request, meaning it only\nwants to update the user's presence `status` on the server.\n\nOtherwise, also requests the server return user presence data for all\nusers in the organization, which is further specified by the\n[`last_update_id`](#parameter-last_update_id) parameter.\n", - "example": false, - "default": false - }, - "slim_presence": { - "type": "boolean", - "description": "Legacy parameter for configuring the format (modern or legacy) in\nwhich the server will return user presence data for the organization.\n\nModern clients should use\n[`last_update_id`](#parameter-last_update_id), which guarantees that\nuser presence data will be returned in the modern format, and\nshould not pass this parameter as `true` unless interacting with an\nolder server.\n\nLegacy clients that do not yet support `last_update_id` may use the\nvalue of `true` to request the modern format for user presence data.\n\n**Note**: The legacy format for user presence data will be removed\nentirely in a future release.\n\n**Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using\nthe modern `last_update_id` parameter is the recommended way to\nrequest the modern format for user presence data.\n\nNew in Zulip 3.0 (no feature level as it was an unstable API at that\npoint).\n", - "example": false, - "default": false, - "deprecated": true - }, - "status": { - "type": "string", - "enum": ["idle", "active"], - "description": "The status of the user on this client.\n\nClients should report the user as `\"active\"` on this device if the client\nknows that the user is presently using the device (and thus would\npotentially see a notification immediately), even if the user\nhas not directly interacted with the Zulip client.\n\nOtherwise, it should report the user as `\"idle\"`.\n\nSee the related [`new_user_input`](#parameter-new_user_input) parameter\nfor how a client should report whether the user is actively using the\nZulip client.\n", - "example": "active" - } - }, - "required": ["status"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": ["result", "msg"], - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "presence_last_update_id": { - "type": "integer", - "description": "The identifier for the latest user presence data returned in\nthe `presences` data of the response.\n\nIf a value was passed for `last_update_id`, then this is\nguaranteed to be equal to or greater than that value. If it\nis the same value, then that indicates to the client that\nthere were no updates to previously received user presence\ndata.\n\nThe client should then pass this value as the `last_update_id`\nparameter when it next queries this endpoint, in order to only\nreceive new user presence data and avoid redundantly fetching\nalready known information.\n\nThis will be `-1` if no value was passed for\n[`last_update_id`](#parameter-last_update_id) and no user\npresence data was returned by the server. This can happen, for\nexample, if an organization has disabled presence.\n\n**Changes**: New in Zulip 9.0 (feature level 263).\n" - }, - "server_timestamp": { - "type": "number", - "description": "Only present if `ping_only` is `false`.\n\nThe time when the server fetched the `presences` data included\nin the response.\n" - }, - "presences": { - "type": "object", - "description": "Only present if `ping_only` is `false`.\n\nA dictionary where each entry describes the presence details\nof a user in the Zulip organization. Entries can be in either\nthe modern presence format or the legacy presence format.\n\nThese entries will be the modern presence format when the\n`last_updated_id` parameter is passed, or when the deprecated\n`slim_presence` parameter is `true`.\n\nIf the deprecated `slim_presence` parameter is `false` and the\n`last_updated_id` parameter is omitted, the entries will be in\nthe legacy presence API format.\n\n**Note**: The legacy presence format should only be used when\ninteracting with old servers. It will be removed as soon as\ndoing so is practical.\n", - "additionalProperties": { - "description": "Will be one of these two formats (modern or legacy) for user\npresence data:\n", - "oneOf": [ - { - "$ref": "#/components/schemas/ModernPresenceFormat" - }, - { - "type": "object", - "description": "`{user_email}`: Presence data (legacy format) for the user with\nthe specified Zulip API email.\n", - "additionalProperties": { - "$ref": "#/components/schemas/LegacyPresenceFormat" - } - } - ] - } - } - } - } - ] - }, - "examples": { - "modern-presence-format-example": { - "description": "Modern presence format:\n", - "value": { - "msg": "", - "presences": { - "10": { - "idle_timestamp": 1656958530, - "active_timestamp": 1656958520 - } - }, - "result": "success", - "server_timestamp": 1656958539.6287155, - "presence_last_update_id": 1000 - } - }, - "legacy-presence-format-example": { - "description": "Legacy presence format:\n", - "value": { - "msg": "", - "presences": { - "user@example.com": { - "aggregated": { - "client": "website", - "status": "idle", - "timestamp": 1594825445 - }, - "website": { - "client": "website", - "status": "idle", - "timestamp": 1594825445, - "pushable": false - } - } - }, - "result": "success", - "server_timestamp": 1656958539.6287155, - "presence_last_update_id": 1000 - } - } - } - } - } - } - } - } - }, - "/users/me/status": { - "post": { - "operationId": "update-status", - "summary": "Update your status", - "tags": ["users"], - "description": "Change your [status](/help/status-and-availability).\n\nA request to this endpoint will only change the parameters passed.\nFor example, passing just `status_text` requests a change in the status\ntext, but will leave the status emoji unchanged.\n\nClients that wish to set the user's status to a specific value should\npass all supported parameters.\n\n**Changes**: In Zulip 5.0 (feature level 86), added support for\n`emoji_name`, `emoji_code`, and `reaction_type` parameters.\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "status_text": { - "type": "string", - "description": "The text content of the status message. Sending the empty string\nwill clear the user's status.\n\n**Note**: The limit on the size of the message is 60 characters.\n", - "example": "on vacation" - }, - "away": { - "deprecated": true, - "type": "boolean", - "description": "Whether the user should be marked as \"away\".\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n", - "example": true - }, - "emoji_name": { - "type": "string", - "description": "The name for the emoji to associate with this status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "car" - }, - "emoji_code": { - "type": "string", - "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "1f697" - }, - "reaction_type": { - "type": "string", - "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n", - "example": "unicode_emoji" - } - } - }, - "encoding": { - "away": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Client did not pass any new values.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when no changes were requested:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "status_text is too long (limit: 60 characters)", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the\n`status_text` message exceeds the limit of\n60 characters:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when `emoji_name` is not specified\nbut `emoji_code` or `reaction_type` is specified:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Emoji 'invalid' does not exist", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the emoji name does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid emoji name.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the emoji name is invalid:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid custom emoji.", - "code": "BAD_REQUEST" - }, - "description": "An example JSON error response when the custom emoji is invalid:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/users/me/{stream_id}/topics": { - "get": { - "operationId": "get-stream-topics", - "summary": "Get topics in a channel", - "tags": ["channels"], - "description": "Get all topics the user has access to in a specific channel.\n\nNote that for [private channels with\nprotected history](/help/channel-permissions#private-channels),\nthe user will only have access to topics of messages sent after they\n[subscribed to](/api/subscribe) the channel. Similarly, a user's\n[bot](/help/bots-overview#bot-type) will only have access to messages\nsent after the bot was subscribed to the channel, instead of when the\nuser subscribed.\n", - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - }, - { - "name": "allow_empty_topic_name", - "in": "query", - "description": "Whether the client supports processing the empty string as\na topic name in the returned data.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously,\nthe empty string was not a valid topic.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "topics": { - "type": "array", - "description": "An array of objects with information about user-accessible\ntopics in the specified channel, sorted by recency (i.e.,\nthe topic with the most recent message is ordered first).\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "max_id": { - "description": "The message ID of the last message sent to this topic.\n", - "type": "integer" - }, - "name": { - "description": "The name of the topic.\n", - "type": "string" - } - } - } - } - }, - "example": { - "msg": "", - "result": "success", - "topics": [ - { - "max_id": 26, - "name": "Denmark3" - }, - { - "max_id": 23, - "name": "Denmark1" - }, - { - "max_id": 6, - "name": "Denmark2" - } - ] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the user is attempting to fetch the topics\nof a non-existing channel (or also a private channel they don't have access to):\n" - } - ] - } - } - } - } - } - } - }, - "/users/me/subscriptions": { - "get": { - "operationId": "get-subscriptions", - "summary": "Get subscribed channels", - "tags": ["channels"], - "description": "Get all channels that the user is subscribed to.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": [""] - } - }, - { - "type": "exclude", - "description": "You may pass the `include_subscribers` query parameter as follows:\n", - "parameters": { - "enum": [""] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/IncludeSubscribers" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": ["subscriptions"], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "subscriptions": { - "type": "array", - "description": "A list of dictionaries where each dictionary contains\ninformation about one of the subscribed channels.\n\n**Changes**: Removed `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n", - "items": { - "$ref": "#/components/schemas/Subscription" - } - } - }, - "example": { - "msg": "", - "result": "success", - "subscriptions": [ - { - "audible_notifications": true, - "color": "#e79ab5", - "creator_id": null, - "description": "A Scandinavian country", - "desktop_notifications": true, - "is_archived": false, - "is_muted": false, - "invite_only": false, - "name": "Denmark", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 1, - "subscribers": [7, 10, 11, 12, 14] - }, - { - "audible_notifications": true, - "color": "#e79ab5", - "creator_id": 8, - "description": "Located in the United Kingdom", - "desktop_notifications": true, - "is_archived": false, - "is_muted": false, - "invite_only": false, - "name": "Scotland", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 3, - "subscribers": [7, 11, 12, 14] - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "subscribe", - "summary": "Subscribe to a channel", - "tags": ["channels"], - "description": "Subscribe one or more users to one or more channels.\n\nIf any of the specified channels do not exist, they are automatically\ncreated. The initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\nNote that the ability to subscribe oneself and/or other users\nto a specified channel depends on the [channel's permissions\nsettings](/help/channel-permissions).\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n\nBefore Zulip 10.0 (feature level 357), the\n`can_subscribe_group` permission, which allows members of the\ngroup to subscribe themselves to the channel, did not exist.\n\nBefore Zulip 10.0 (feature level 349), a user cannot subscribe\nother users to a private channel without being subscribed\nto that channel themselves. Now, If a user is part of\n`can_add_subscribers_group`, they can subscribe themselves or other\nusers to a private channel without being subscribed to that channel.\n\nRemoved `stream_post_policy` and `is_announcement_only`\nparameters in Zulip 10.0 (feature level 333), as permission to post\nin the channel is now controlled by `can_send_message_group`.\n\nBefore Zulip 8.0 (feature level 208), if a user specified by the\n[`principals`][principals-param] parameter was a deactivated user,\nor did not exist, then an HTTP status code of 403 was returned with\n`code: \"UNAUTHORIZED_PRINCIPAL\"` in the error response. As of this\nfeature level, an HTTP status code of 400 is returned with\n`code: \"BAD_REQUEST\"` in the error response for these cases.\n\n[principals-param]: /api/subscribe#parameter-principals\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["subscriptions"] - } - }, - { - "type": "include", - "description": "To subscribe another user to a channel, you may pass in\nthe `principals` parameter, like so:\n", - "parameters": { - "enum": ["subscriptions", "principals"] - } - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "subscriptions": { - "description": "A list of dictionaries containing the key `name` and value\nspecifying the name of the channel to subscribe. If the channel does not\nexist a new channel is created. The description of the channel created can\nbe specified by setting the dictionary key `description` with an\nappropriate value.\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "The name of the channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n" - }, - "description": { - "type": "string", - "description": "The [description](/help/change-the-channel-description)\nto use for a new channel being created, in text/markdown format.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n" - } - }, - "required": ["name"], - "example": { - "no-description": { - "value": { - "name": "Verona" - } - }, - "with-description": { - "value": { - "name": "Verona", - "description": "Italian city" - } - } - } - }, - "example": [ - { - "name": "Verona", - "description": "Italian city" - } - ] - }, - "principals": { - "$ref": "#/components/schemas/Principals" - }, - "authorization_errors_fatal": { - "description": "A boolean specifying whether authorization errors (such as when the\nrequesting user is not authorized to access a private channel) should be\nconsidered fatal or not. When `true`, an authorization error is reported\nas such. When set to `false`, the response will be a 200 and any channels\nwhere the request encountered an authorization error will be listed\nin the `unauthorized` key.\n", - "type": "boolean", - "default": true, - "example": false - }, - "announce": { - "description": "If one of the channels specified did not exist previously and is thus created\nby this call, this determines whether [notification bot](/help/configure-automated-notices)\nwill send an announcement about the new channel's creation.\n", - "type": "boolean", - "default": false, - "example": true - }, - "invite_only": { - "description": "As described above, this endpoint will create a new channel if passed\na channel name that doesn't already exist. This parameters and the ones\nthat follow are used to request an initial configuration of a created\nchannel; they are ignored for channels that already exist.\n\nThis parameter determines whether any newly created channels will be\nprivate channels.\n", - "type": "boolean", - "default": false, - "example": true - }, - "is_web_public": { - "description": "This parameter determines whether any newly created channels will be\nweb-public channels.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current use to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 98).\n", - "type": "boolean", - "default": false, - "example": true - }, - "is_default_stream": { - "description": "This parameter determines whether any newly created channels will be\nadded as [default channels][default-channels] for new users joining\nthe organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n\n**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status\ncould only be changed using the [dedicated API endpoint](/api/add-default-stream).\n", - "type": "boolean", - "default": false, - "example": true - }, - "history_public_to_subscribers": { - "$ref": "#/components/schemas/HistoryPublicToSubscribers" - }, - "message_retention_days": { - "$ref": "#/components/schemas/MessageRetentionDays" - }, - "topics_policy": { - "$ref": "#/components/schemas/TopicsPolicy" - }, - "can_add_subscribers_group": { - "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" - }, - "can_remove_subscribers_group": { - "$ref": "#/components/schemas/CanRemoveSubscribersGroup" - }, - "can_administer_channel_group": { - "$ref": "#/components/schemas/CanAdministerChannelGroup" - }, - "can_delete_any_message_group": { - "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" - }, - "can_delete_own_message_group": { - "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" - }, - "can_move_messages_out_of_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" - }, - "can_move_messages_within_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" - }, - "can_send_message_group": { - "$ref": "#/components/schemas/CanSendMessageGroup" - }, - "can_subscribe_group": { - "$ref": "#/components/schemas/CanSubscribeGroup" - }, - "can_resolve_topics_group": { - "$ref": "#/components/schemas/CanResolveTopicsGroup" - }, - "folder_id": { - "description": "This parameter adds the newly created channel to the specified\n[channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "type": "integer", - "example": 1 - }, - "send_new_subscription_messages": { - "$ref": "#/components/schemas/SendNewSubscriptionMessages" - } - }, - "required": ["subscriptions"] - }, - "encoding": { - "subscriptions": { - "contentType": "application/json" - }, - "principals": { - "contentType": "application/json" - }, - "authorization_errors_fatal": { - "contentType": "application/json" - }, - "announce": { - "contentType": "application/json" - }, - "invite_only": { - "contentType": "application/json" - }, - "is_web_public": { - "contentType": "application/json" - }, - "is_default_stream": { - "contentType": "application/json" - }, - "history_public_to_subscribers": { - "contentType": "application/json" - }, - "topics_policy": { - "contentType": "application/json" - }, - "can_add_subscribers_group": { - "contentType": "application/json" - }, - "can_remove_subscribers_group": { - "contentType": "application/json" - }, - "can_administer_channel_group": { - "contentType": "application/json" - }, - "can_delete_any_message_group": { - "contentType": "application/json" - }, - "can_delete_own_message_group": { - "contentType": "application/json" - }, - "can_move_messages_out_of_channel_group": { - "contentType": "application/json" - }, - "can_move_messages_within_channel_group": { - "contentType": "application/json" - }, - "can_send_message_group": { - "contentType": "application/json" - }, - "can_subscribe_group": { - "contentType": "application/json" - }, - "can_resolve_topics_group": { - "contentType": "application/json" - }, - "folder_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "subscribed": { - "type": "object", - "description": "A dictionary where the key is the ID of the user and the value\nis a list of the names of the channels that user was subscribed\nto as a result of the request.\n\n**Changes**: Before Zulip 10.0 (feature level 289), the user\nkeys were Zulip API email addresses, not user ID.\n", - "additionalProperties": { - "description": "`{id}`: List of the names of the channels that were subscribed\nto as a result of the query.\n", - "type": "array", - "items": { - "type": "string" - } - } - }, - "already_subscribed": { - "type": "object", - "description": "A dictionary where the key is the ID of the user and the value\nis a list of the names of the channels that where the user was\nnot added as a subscriber in this request, because they were\nalready a subscriber.\n\n**Changes**: Before Zulip 10.0 (feature level 289), the user\nkeys were Zulip API email addresses, not user IDs.\n", - "additionalProperties": { - "description": "`{id}`: List of the names of the channels that the user is\nalready subscribed to.\n", - "type": "array", - "items": { - "type": "string" - } - } - }, - "unauthorized": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of names of channels that the requesting user/bot was not\nauthorized to subscribe to. Only present if `\"authorization_errors_fatal\": false`.\n" - }, - "new_subscription_messages_sent": { - "type": "boolean", - "description": "Only present if the parameter `send_new_subscription_messages`\nin the request was `true`.\n\nWhether Notification Bot DMs in fact sent to the added\nsubscribers as requested by the `send_new_subscription_messages`\nparameter. Clients may find this value useful to communicate\nwith users about the effect of this request.\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n" - } - }, - "example": { - "already_subscribed": { - "1": ["testing-help"] - }, - "msg": "", - "result": "success", - "subscribed": { - "2": ["testing-help"] - } - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "msg": "Unable to access channel (private).", - "result": "error", - "code": "BAD_REQUEST" - }, - "description": "An example JSON response for when the requesting user does not have\naccess to a private channel and `\"authorization_errors_fatal\": true`:\n" - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "update-subscriptions", - "summary": "Update subscriptions", - "tags": ["channels"], - "description": "Update which channels you are subscribed to.\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "delete": { - "description": "A list of channel names to unsubscribe from.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["Verona", "Denmark"] - }, - "add": { - "description": "A list of objects describing which channels to subscribe to, optionally\nincluding per-user subscription parameters (e.g. color) and if the\nchannel is to be created, its description.\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string" - }, - "color": { - "type": "string" - }, - "description": { - "type": "string" - } - } - }, - "example": [ - { - "name": "Verona" - }, - { - "name": "Denmark", - "color": "#e79ab5", - "description": "A Scandinavian country" - } - ] - } - } - }, - "encoding": { - "delete": { - "contentType": "application/json" - }, - "add": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": [ - "subscribed", - "already_subscribed", - "removed" - ], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "subscribed": { - "type": "object", - "description": "A dictionary where the key is the Zulip API email\naddress of the user/bot and the value is a\nlist of the names of the channels that were\nsubscribed to as a result of the query.\n", - "additionalProperties": { - "description": "`{email_id}`: A list of the names of channels that\nthe user was subscribed to as a result of the query.\n", - "type": "array", - "items": { - "type": "string" - } - } - }, - "already_subscribed": { - "type": "object", - "description": "A dictionary where the key is the Zulip API email\naddress of the user/bot and the value is a\nlist of the names of the channels that the\nuser/bot is already subscribed to.\n", - "additionalProperties": { - "description": "`{email_id}`: A list of the names of channels that\nthe user was already subscribed to.\n", - "type": "array", - "items": { - "type": "string" - } - } - }, - "not_removed": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of the names of channels that the user\nis already unsubscribed from, and hence\ndoesn't need to be unsubscribed.\n" - }, - "removed": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of the names of channels which were unsubscribed\nfrom as a result of the query.\n" - }, - "new_subscription_messages_sent": { - "type": "boolean", - "description": "Only present if the parameter `send_new_subscription_messages`\nin the request was `true`.\n\nWhether Notification Bot DMs in fact sent to the added\nsubscribers as requested by the `send_new_subscription_messages`\nparameter. Clients may find this value useful to communicate\nwith users about the effect of this request.\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n" - } - }, - "example": { - "msg": "", - "subscribed": {}, - "already_subscribed": { - "iago@zulip.com": ["Verona"] - }, - "not_removed": [], - "removed": ["testing-help"], - "result": "success" - } - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "unsubscribe", - "summary": "Unsubscribe from a channel", - "tags": ["channels"], - "description": "Unsubscribe yourself or other users from one or more channels.\n\nIn addition to managing the current user's subscriptions, this\nendpoint can be used to remove other users from channels. This\nis possible in 3 situations:\n\n- Organization administrators can remove any user from any\n channel.\n- Users can remove a bot that they own from any channel that\n the user [can access](/help/channel-permissions).\n- Users can unsubscribe any user from a channel if they [have\n access](/help/channel-permissions) to the channel and are a\n member of the [user group](/api/get-user-groups) specified\n by the [`can_remove_subscribers_group`][can-remove-parameter]\n for the channel.\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n\nBefore Zulip 8.0 (feature level 208), if a user specified by\nthe [`principals`][principals-param] parameter was a\ndeactivated user, or did not exist, then an HTTP status code\nof 403 was returned with `code: \"UNAUTHORIZED_PRINCIPAL\"` in\nthe error response. As of this feature level, an HTTP status\ncode of 400 is returned with `code: \"BAD_REQUEST\"` in the\nerror response for these cases.\n\nBefore Zulip 8.0 (feature level 197),\nthe `can_remove_subscribers_group` setting\nwas named `can_remove_subscribers_group_id`.\n\nBefore Zulip 7.0 (feature level 161), the\n`can_remove_subscribers_group_id` for all channels was always\nthe system group for organization administrators.\n\nBefore Zulip 6.0 (feature level 145), users had no special\nprivileges for managing bots that they own.\n\n[principals-param]: /api/unsubscribe#parameter-principals\n[can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "description": "**Note**: Unsubscribing another user from a channel requires\nadministrative privileges.\n", - "parameters": { - "enum": ["subscriptions"] - } - }, - { - "type": "exclude", - "parameters": { - "enum": [""] - }, - "description": "You may specify the `principals` parameter like so:\n" - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "subscriptions": { - "description": "A list of channel names to unsubscribe from. This parameter is called\n`streams` in our Python API.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["Verona", "Denmark"] - }, - "principals": { - "$ref": "#/components/schemas/Principals" - } - }, - "required": ["subscriptions"] - }, - "encoding": { - "subscriptions": { - "contentType": "application/json" - }, - "principals": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "not_removed": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of the names of channels that the user is already unsubscribed\nfrom, and hence doesn't need to be unsubscribed.\n" - }, - "removed": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of the names of channels which were unsubscribed from as a result\nof the query.\n" - } - }, - "example": { - "msg": "", - "not_removed": [], - "removed": ["testing-help"], - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/NonExistingChannelNameError" - }, - { - "description": "A typical failed JSON response for when the target channel does not exist:\n" - } - ] - } - } - } - } - } - } - }, - "/users/me/subscriptions/muted_topics": { - "patch": { - "deprecated": true, - "operationId": "mute-topic", - "summary": "Topic muting", - "tags": ["channels"], - "description": "[Mute or unmute a topic](/help/mute-a-topic) within a channel that\nthe current user is subscribed to.\n\n**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting\nto newer servers should use the [POST /user_topics](/api/update-user-topic)\nendpoint, as this endpoint may be removed in a future release.\n\nBefore Zulip 7.0 (feature level 169), this endpoint\nreturned an error if asked to mute a topic that was already muted\nor asked to unmute a topic that had not previously been muted.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["stream_id"] - } - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the channel to access.\n\nClients must provide either `stream` or `stream_id` as a parameter\nto this endpoint, but not both.\n\n**Changes**: New in Zulip 2.0.0.\n", - "type": "integer", - "example": 43 - }, - "stream": { - "description": "The name of the channel to access.\n\nClients must provide either `stream` or `stream_id` as a parameter\nto this endpoint, but not both. Clients should use `stream_id`\ninstead of the `stream` parameter when possible.\n", - "type": "string", - "example": "Denmark" - }, - "topic": { - "description": "The topic to (un)mute. Note that the request will succeed regardless of\nwhether any messages have been sent to the specified topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n", - "type": "string", - "example": "dinner" - }, - "op": { - "description": "Whether to mute (`add`) or unmute (`remove`) the provided topic.\n", - "type": "string", - "enum": ["add", "remove"], - "example": "add" - } - }, - "required": ["topic", "op"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/mobile_push/test_notification": { - "post": { - "deprecated": true, - "operationId": "test-notify", - "summary": "Send a test notification to mobile device(s)", - "tags": ["mobile"], - "description": "Trigger sending a test push notification to the user's\nselected mobile device or all of their mobile devices.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 420).\nClients connecting to newer servers and with E2EE push\nnotifications support should use the\n[Send an E2EE test notification to mobile device(s)](/api/e2ee-test-notify)\nendpoint, as this endpoint will be removed in a future release.\n\nStarting with Zulip 8.0 (feature level 234), test\nnotifications sent via this endpoint use `test` rather than\n`test-by-device-token` in the `event` field. Also, as of this\nfeature level, all mobile push notifications now include a\n`realm_name` field.\n\nNew in Zulip 8.0 (feature level 217).\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token": { - "description": "The push token for the device to which to send the test notification.\n\nIf this parameter is not submitted, the test notification will be sent\nto all of the user's devices registered on the server.\n\nA mobile client should pass this parameter, to avoid triggering a test\nnotification for other clients.\n", - "type": "string", - "example": "111222" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/JsonSuccess" - } - } - } - }, - "400": { - "description": "Bad request.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/InvalidPushDeviceTokenError" - }, - { - "$ref": "#/components/schemas/InvalidRemotePushDeviceTokenError" - } - ] - } - } - } - } - } - } - }, - "/mobile_push/e2ee/test_notification": { - "post": { - "operationId": "e2ee-test-notify", - "summary": "Send an E2EE test notification to mobile device(s)", - "tags": ["mobile"], - "description": "Trigger sending an end-to-end encrypted (E2EE) test push notification\nto the user's selected mobile device or all of their mobile devices.\n\n**Changes**: New in Zulip 11.0 (feature level 420).\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "push_account_id": { - "description": "The push account ID for the device to which to send the test notification.\n\nIf this parameter is not submitted, the E2EE test notification will\nbe sent to all of the user's devices registered on the server.\n\nA mobile client should pass this parameter, to avoid triggering a test\nnotification for other clients.\n\nSee [`POST /mobile_push/register`](/api/register-push-device)\nfor details on push account IDs.\n", - "type": "integer", - "example": 111222 - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/JsonSuccess" - } - } - } - }, - "400": { - "description": "Bad request.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/NoActivePushDeviceError" - } - ] - } - } - } - }, - "403": { - "description": "Forbidden.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/PushNotificationAdminActionRequiredError" - } - ] - } - } - } - }, - "502": { - "description": "Bad gateway.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/FailedToConnectBouncerError" - }, - { - "$ref": "#/components/schemas/InternalBouncerServerError" - } - ] - } - } - } - } - } - } - }, - "/mobile_push/register": { - "post": { - "operationId": "register-push-device", - "summary": "Register E2EE push device", - "tags": ["mobile"], - "description": "Register a device to receive end-to-end encrypted mobile push notifications.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token_kind": { - "description": "Whether the token was generated by FCM or APNs.\n", - "type": "string", - "enum": ["fcm", "apns"], - "example": "fcm" - }, - "push_account_id": { - "description": "A random integer generated by the client that will be included\nin mobile push notifications along with encrypted payloads to\nidentify pushes as being related to this registration.\nMust be unique in the client's table of accounts.\n", - "type": "integer", - "example": 2408 - }, - "push_public_key": { - "description": "Public part of the asymmetric key pair generated by the client\nusing NaCl (the Networking and Cryptography Library), encoded\nusing a RFC 4648 standard base64 encoder.\n\nIt is used to encrypt notifications for delivery to the client.\n", - "type": "string", - "example": "push-public-key" - }, - "bouncer_public_key": { - "description": "Which of the bouncer's public keys the client used to encrypt the\n`PushRegistration` dictionary.\n\nWhen the bouncer rotates the key, a new asymmetric key pair is created,\nand the new public key is baked into a new client release. Because\nthe bouncer routinely rotates key, this field clarifies which\npublic key the client is using.\n", - "type": "string", - "example": "bouncer-public-key" - }, - "encrypted_push_registration": { - "description": "Ciphertext generated by encrypting a `PushRegistration` dictionary\nusing the `bouncer_public_key`, encoded using a RFC 4648 standard\nbase64 encoder.\n\nThe `PushRegistration` dictionary contains the fields `token`,\n`token_kind`, `timestamp`, and (for iOS devices) `ios_app_id`.\nThe dictionary is JSON-encoded before encryption.\n", - "type": "string", - "example": "encrypted-push-registration-data" - } - }, - "required": [ - "token_kind", - "push_account_id", - "push_public_key", - "bouncer_public_key", - "encrypted_push_registration" - ] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Server is not configured to use push notification service.", - "code": "PUSH_SERVICE_NOT_CONFIGURED" - }, - "description": "Error when the server is not configured to use push notification service:\n" - } - ] - } - } - } - } - } - } - }, - "/remotes/push/e2ee/register": { - "post": { - "operationId": "register-remote-push-device", - "summary": "Register E2EE push device to bouncer", - "tags": ["mobile"], - "description": "Register a push device to bouncer to receive end-to-end encrypted\nmobile push notifications.\n\nSelf-hosted servers use this endpoint to asynchronously register\na push device to the bouncer server after receiving a request from\nthe mobile client to [register E2EE push device](/api/register-push-device).\n\nIt is not meant to be used by mobile clients directly.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "realm_uuid": { - "description": "The UUID of the realm to which the push device\nbeing registered belongs.\n", - "type": "string", - "example": "9aa61d0b-8ce5-488d-8e9e-fedc346e6836" - }, - "push_account_id": { - "description": "The `push_account_id` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", - "type": "integer", - "example": 2408 - }, - "encrypted_push_registration": { - "description": "The `encrypted_push_registration` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", - "type": "string", - "example": "encrypted-push-registration-data" - }, - "bouncer_public_key": { - "description": "The `bouncer_public_key` value provided by the mobile client\nto [register E2EE push device](/api/register-push-device).\n", - "type": "string", - "example": "bouncer-public-key" - } - }, - "required": [ - "realm_uuid", - "push_account_id", - "encrypted_push_registration", - "bouncer_public_key" - ] - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": ["device_id"], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "device_id": { - "type": "integer", - "description": "Unique identifier assigned by the bouncer for the registration.\n", - "example": 2408 - } - }, - "example": { - "device_id": 2408, - "msg": "", - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "INVALID_BOUNCER_PUBLIC_KEY", - "msg": "Invalid bouncer_public_key", - "result": "error" - }, - "description": "An example JSON response for when the given `bouncer_public_key` is invalid:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "REQUEST_EXPIRED", - "msg": "Request expired", - "result": "error" - }, - "description": "An example JSON response for when the given `encrypted_push_registration` is stale:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid encrypted_push_registration", - "result": "error" - }, - "description": "An example JSON response for when either the bouncer fails to decrypt\nthe given `encrypted_push_registration` or the decrypted data is invalid:\n" - } - ] - } - ] - } - } - } - }, - "403": { - "description": "Forbidden.\n", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "MISSING_REMOTE_REALM", - "msg": "Organization not registered", - "result": "error" - }, - "description": "An example JSON response for when no realm is registered for\nthe authenticated server on the bouncer for the given `realm_uuid`:\n" - } - ] - } - } - } - } - } - } - }, - "/user_topics": { - "post": { - "operationId": "update-user-topic", - "summary": "Update personal preferences for a topic", - "tags": ["channels"], - "description": "This endpoint is used to update the personal preferences for a topic,\nsuch as the topic's visibility policy, which is used to implement\n[mute a topic](/help/mute-a-topic) and related features.\n\nThis endpoint can be used to update the visibility policy for the single\nchannel and topic pair indicated by the parameters for a user.\n\n**Changes**: New in Zulip 7.0 (feature level 170). Previously,\ntoggling whether a topic was muted or unmuted was managed by the\n[PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "stream_id": { - "description": "The ID of the channel to access.\n", - "type": "integer", - "example": 1 - }, - "topic": { - "description": "The topic for which the personal preferences needs to be updated.\nNote that the request will succeed regardless of whether\nany messages have been sent to the specified topic.\n\nClients should use the `max_topic_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum topic length.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", - "type": "string", - "example": "dinner" - }, - "visibility_policy": { - "description": "Controls which visibility policy to set.\n\n- 0 = None. Removes the visibility policy previously set for the topic.\n- 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a channel.\n- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted channel.\n- 3 = Followed. [Follows the topic](/help/follow-a-topic).\n\nIn an unmuted channel, a topic visibility policy of unmuted will have the\nsame effect as the \"None\" visibility policy.\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n", - "type": "integer", - "enum": [0, 1, 2, 3], - "example": 1 - } - }, - "required": ["stream_id", "topic", "visibility_policy"] - }, - "encoding": { - "stream_id": { - "contentType": "application/json" - }, - "visibility_policy": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/users/me/muted_users/{muted_user_id}": { - "post": { - "operationId": "mute-user", - "summary": "Mute a user", - "tags": ["users"], - "description": "[Mute a user](/help/mute-a-user) from the perspective of the requesting\nuser. Messages sent by muted users will be automatically marked as read\nand hidden for the user who muted them.\n\nMuted users should be implemented by clients as follows:\n\n- The server will immediately mark all messages sent by the muted\n user as read. This will automatically clear any existing mobile\n push notifications related to the muted user.\n- The server will mark any new messages sent by the muted user as read\n for the requesting user's account, which prevents all email and mobile\n push notifications.\n- Clients should exclude muted users from presence lists or other UI\n for viewing or composing one-on-one direct messages. One-on-one direct\n messages sent by muted users should be hidden everywhere in the Zulip UI.\n- Channel messages and group direct messages sent by the muted\n user should avoid displaying the content and name/avatar,\n but should display that N messages by a muted user were\n hidden (so that it is possible to interpret the messages by\n other users who are talking with the muted user).\n- Group direct message conversations including the muted user\n should display muted users as \"Muted user\", rather than\n showing their name, in lists of such conversations, along with using\n a blank grey avatar where avatars are displayed.\n- Administrative/settings UI elements for showing \"All users that exist\n on this channel or realm\", e.g. for organization\n administration or showing channel subscribers, should display\n the user's name as normal.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", - "parameters": [ - { - "$ref": "#/components/parameters/MutedUserId" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Cannot mute self", - "result": "error" - }, - "description": "An example JSON response for when the user ID is the current\nuser's ID:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "No such user", - "result": "error" - }, - "description": "An example JSON response for when the user is nonexistent or inaccessible:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "User already muted", - "result": "error" - }, - "description": "An example JSON response for when the user is already muted:\n" - } - ] - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "unmute-user", - "summary": "Unmute a user", - "tags": ["users"], - "description": "[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users)\nfrom the perspective of the requesting user.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", - "parameters": [ - { - "$ref": "#/components/parameters/MutedUserId" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "No such user", - "result": "error" - }, - "description": "An example JSON response for when the user is nonexistent or inaccessible:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "User is not muted", - "result": "error" - }, - "description": "An example JSON response for when the user is not previously muted:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/users/me/apns_device_token": { - "post": { - "deprecated": true, - "operationId": "add-apns-token", - "summary": "Add an APNs device token", - "tags": ["users"], - "description": "This endpoint adds an APNs device token to register for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token": { - "description": "The token provided by the device.\n", - "type": "string", - "example": "c0ffee" - }, - "appid": { - "description": "The ID of the Zulip app that is making the request.\n\n**Changes**: In Zulip 8.0 (feature level 223), this parameter was made\nrequired. Previously, if it was unspecified, the server would use a default\nvalue (based on the `ZULIP_IOS_APP_ID` server setting, which\ndefaulted to `\"org.zulip.Zulip\"`).\n", - "type": "string", - "example": "org.zulip.Zulip" - } - }, - "required": ["token", "appid"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when the token's length is invalid\nor it is empty:\n", - "example": { - "result": "error", - "msg": "Empty or invalid length token", - "code": "BAD_REQUEST" - } - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invalid APNS token", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for when the APNs token is invalid:\n" - } - ] - } - ] - } - } - } - } - } - }, - "delete": { - "deprecated": true, - "operationId": "remove-apns-token", - "summary": "Remove an APNs device token", - "tags": ["users"], - "description": "This endpoint removes an APNs device token for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that registration.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token": { - "description": "The token provided by the device.\n", - "type": "string", - "example": "c0ffee" - } - }, - "required": ["token"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when the token's length is invalid\nor it is empty:\n", - "example": { - "result": "error", - "msg": "Empty or invalid length token", - "code": "BAD_REQUEST" - } - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Token does not exist", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for when the token does not exist:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/users/me/android_gcm_reg_id": { - "post": { - "deprecated": true, - "operationId": "add-fcm-token", - "summary": "Add an FCM registration token", - "tags": ["users"], - "description": "This endpoint adds an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token": { - "description": "The token provided by the device.\n", - "type": "string", - "example": "android-token" - } - }, - "required": ["token"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when the token's length is invalid\nor is empty:\n", - "example": { - "result": "error", - "msg": "Empty or invalid length token", - "code": "BAD_REQUEST" - } - } - ] - } - } - } - } - } - }, - "delete": { - "deprecated": true, - "operationId": "remove-fcm-token", - "summary": "Remove an FCM registration token", - "tags": ["users"], - "description": "This endpoint removes an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that registration.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "token": { - "description": "The token provided by the device.\n", - "type": "string", - "example": "android-token" - } - }, - "required": ["token"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "A typical failed JSON response for when the token's length is invalid\nor is empty:\n", - "example": { - "result": "error", - "msg": "Empty or invalid length token", - "code": "BAD_REQUEST" - } - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Token does not exist", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for when the token does not exist:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/users/{user_id}/subscriptions/{stream_id}": { - "get": { - "operationId": "get-subscription-status", - "summary": "Get subscription status", - "tags": ["channels"], - "description": "Check whether a user is subscribed to a channel.\n\n**Changes**: New in Zulip 3.0 (feature level 12).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - }, - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "is_subscribed": { - "type": "boolean", - "description": "Whether the user is subscribed to the channel.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "is_subscribed": false - } - } - ] - } - } - } - } - } - } - }, - "/realm/emoji/{emoji_name}": { - "post": { - "operationId": "upload-custom-emoji", - "summary": "Upload custom emoji", - "tags": ["server_and_organizations"], - "description": "This endpoint is used to upload a custom emoji for use in the user's\norganization. Access to this endpoint depends on the\n[organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji).\n", - "x-parameter-description": "As described above, the image file to upload must be provided in the\nrequest's body.\n\n## Maximum file size\n\nThe maximum file size for uploads can be configured by the\nadministrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB`\nin the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults\nto 5MB.\n\n[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings\n", - "parameters": [ - { - "name": "emoji_name", - "required": true, - "in": "path", - "description": "The name that should be associated with the uploaded emoji image/gif.\nThe emoji name can only contain letters, numbers, dashes, and spaces.\nUpper and lower case letters are treated the same, and underscores (\\_)\nare treated the same as spaces (consistent with how the Zulip UI\nhandles emoji).\n", - "schema": { - "type": "string" - }, - "example": "smile" - } - ], - "requestBody": { - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "filename": { - "type": "string", - "format": "binary", - "example": "/path/to/img.png" - } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - }, - "delete": { - "operationId": "deactivate-custom-emoji", - "summary": "Deactivate custom emoji", - "tags": ["server_and_organizations"], - "description": "[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from\nthe user's organization.\n\nUsers can only deactivate custom emoji that they added themselves except for\norganization administrators, who can deactivate any custom emoji.\n\nNote that deactivated emoji will still be visible in old messages, reactions,\nuser statuses and channel descriptions.\n\n**Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an\nHTTP status code of 400 when the emoji did not exist, instead of 404.\n", - "parameters": [ - { - "name": "emoji_name", - "required": true, - "in": "path", - "description": "The name of the custom emoji to deactivate.\n", - "schema": { - "type": "string" - }, - "example": "green_tick" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "404": { - "description": "Not Found.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "description": "An example JSON response for when no emoji exists with the provided name:\n", - "example": { - "code": "BAD_REQUEST", - "result": "error", - "msg": "Emoji 'green_tick' does not exist" - } - } - ] - } - } - } - } - } - } - }, - "/realm/emoji": { - "get": { - "operationId": "get-custom-emoji", - "summary": "Get all custom emoji", - "tags": ["server_and_organizations"], - "description": "Get all the custom emoji in the user's organization.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "emoji": { - "type": "object", - "description": "An object that contains `emoji` objects, each identified with their\nemoji ID as the key.\n", - "additionalProperties": { - "$ref": "#/components/schemas/RealmEmoji" - } - } - }, - "example": { - "result": "success", - "msg": "", - "emoji": { - "1": { - "id": "1", - "name": "green_tick", - "source_url": "/user_avatars/1/emoji/images/1.png", - "deactivated": false, - "author_id": 5 - } - } - } - } - ] - } - } - } - } - } - } - }, - "/realm/presence": { - "get": { - "operationId": "get-presence", - "summary": "Get presence of all users", - "tags": ["server_and_organizations"], - "description": "Get the presence information of all the users in an organization.\n\nIf the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level\nsetting is set to `true`, presence information of only accessible\nusers are returned.\n\nComplete Zulip apps are recommended to fetch presence\ninformation when they post their own state using the [`POST\n/presence`](/api/update-presence) API endpoint.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "server_timestamp": { - "type": "number", - "description": "The time when the server fetched the `presences` data included\nin the response.\n" - }, - "presences": { - "type": "object", - "description": "A dictionary where each entry describes the presence details\nof a user in the Zulip organization.\n", - "additionalProperties": { - "type": "object", - "description": "`{user_email}`: Object containing the details of a user's presence.\nThe object's key is the user's Zulip API email.\n", - "additionalProperties": { - "$ref": "#/components/schemas/LegacyPresenceFormat" - } - } - } - }, - "example": { - "msg": "", - "presences": { - "iago@zulip.com": { - "website": { - "client": "website", - "pushable": false, - "status": "active", - "timestamp": 1656958485 - }, - "aggregated": { - "client": "website", - "status": "active", - "timestamp": 1656958485 - } - } - }, - "result": "success", - "server_timestamp": 1656958539.6287155 - } - } - ] - } - } - } - } - } - } - }, - "/realm/profile_fields": { - "get": { - "operationId": "get-custom-profile-fields", - "summary": "Get all custom profile fields", - "tags": ["server_and_organizations"], - "description": "Get all the [custom profile fields](/help/custom-profile-fields)\nconfigured for the user's organization.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "custom_fields": { - "type": "array", - "description": "An array containing all the custom profile fields defined in this\nZulip organization.\n", - "items": { - "$ref": "#/components/schemas/CustomProfileField" - } - } - }, - "example": { - "result": "success", - "msg": "", - "custom_fields": [ - { - "id": 1, - "name": "Phone number", - "type": 1, - "hint": "", - "field_data": "", - "order": 1, - "required": true, - "editable_by_user": false - }, - { - "id": 2, - "name": "Biography", - "type": 2, - "hint": "What are you known for?", - "field_data": "", - "order": 2, - "required": true, - "editable_by_user": true - }, - { - "id": 3, - "name": "Favorite food", - "type": 1, - "hint": "Or drink, if you'd prefer", - "field_data": "", - "order": 3, - "required": false, - "editable_by_user": true - }, - { - "id": 4, - "name": "Favorite editor", - "type": 3, - "hint": "", - "field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}", - "order": 4, - "display_in_profile_summary": true, - "required": true, - "editable_by_user": true - }, - { - "id": 5, - "name": "Birthday", - "type": 4, - "hint": "", - "field_data": "", - "order": 5, - "required": false, - "editable_by_user": false - }, - { - "id": 6, - "name": "Favorite website", - "type": 5, - "hint": "Or your personal blog's URL", - "field_data": "", - "order": 6, - "display_in_profile_summary": true, - "required": false, - "editable_by_user": true - }, - { - "id": 7, - "name": "Mentor", - "type": 6, - "hint": "", - "field_data": "", - "order": 7, - "required": true, - "editable_by_user": false - }, - { - "id": 8, - "name": "GitHub", - "type": 7, - "hint": "Enter your GitHub username", - "field_data": "{\"subtype\":\"github\"}", - "order": 8, - "required": true, - "editable_by_user": true - }, - { - "id": 9, - "name": "Pronouns", - "type": 8, - "hint": "What pronouns should people use to refer to you?", - "order": 9, - "required": false, - "editable_by_user": true - } - ] - } - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "reorder-custom-profile-fields", - "summary": "Reorder custom profile fields", - "tags": ["server_and_organizations"], - "description": "Reorder the custom profile fields in the user's organization.\n\nCustom profile fields are displayed in Zulip UI widgets in order; this\nendpoint allows administrative settings UI to change the field ordering.\n\nThis endpoint is used to implement the dragging feature described in the\n[custom profile fields documentation](/help/custom-profile-fields).\n", - "x-requires-administrator": true, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "order": { - "description": "A list of the IDs of all the custom profile fields defined in this\norganization, in the desired new order.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1] - } - }, - "required": ["order"] - }, - "encoding": { - "order": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - }, - "post": { - "operationId": "create-custom-profile-field", - "summary": "Create a custom profile field", - "tags": ["server_and_organizations"], - "description": "[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.\n", - "x-requires-administrator": true, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The name of the custom profile field, which will appear both in\nuser-facing settings UI for configuring custom profile fields and\nin UI displaying a user's profile.\n", - "type": "string", - "example": "Favorite programming language" - }, - "hint": { - "description": "The help text to be displayed for the custom profile field in user-facing\nsettings UI for configuring custom profile fields.\n", - "type": "string", - "example": "Your favorite programming language." - }, - "field_type": { - "description": "The field type can be any of the supported custom profile field types. See the\n[custom profile fields documentation](/help/custom-profile-fields)\nfor more details on what each type means.\n\n- **1**: Short text\n- **2**: Long text\n- **3**: List of options\n- **4**: Date picker\n- **5**: Link\n- **6**: Person picker\n- **7**: External account\n- **8**: Pronouns\n\n**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).\n", - "type": "integer", - "example": 3 - }, - "field_data": { - "description": "Field types 3 (List of options) and 7 (External account) support storing\nadditional configuration for the field type in the `field_data` attribute.\n\nFor field type 3 (List of options), this attribute is a JSON dictionary\ndefining the choices and the order they will be displayed in the\ndropdown UI for individual users to select an option.\n\nThe interface for field type 7 is not yet stabilized.\n", - "type": "object", - "example": { - "python": { - "text": "Python", - "order": "1" - }, - "java": { - "text": "Java", - "order": "2" - } - } - }, - "display_in_profile_summary": { - "description": "Whether clients should display this profile field in a summary section of a\nuser's profile (or in a more easily accessible \"small profile\").\n\nAt most 2 profile fields may have this property be true in a given\norganization. The \"Long text\" [profile field types][profile-field-types]\nprofile field types cannot be selected to be displayed in profile summaries.\n\nThe \"Person picker\" profile field is also not supported, but that is likely to\nbe temporary.\n\n[profile-field-types]: /help/custom-profile-fields#profile-field-types\n\n**Changes**: New in Zulip 6.0 (feature level 146).\n", - "type": "boolean", - "example": true - }, - "required": { - "description": "Whether an organization administrator has configured this profile field as\nrequired.\n\nBecause the required property is mutable, clients cannot assume that a required\ncustom profile field has a value. The Zulip web application displays a prominent\nbanner to any user who has not set a value for a required field.\n\n**Changes**: New in Zulip 9.0 (feature level 244).\n", - "type": "boolean", - "example": true - }, - "editable_by_user": { - "description": "Whether regular users can edit this profile field on their own account.\n\nNote that organization administrators can edit custom profile fields for any user\nregardless of this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 296).\n", - "type": "boolean", - "example": true - } - }, - "required": ["field_type"] - }, - "encoding": { - "field_type": { - "contentType": "application/json" - }, - "field_data": { - "contentType": "application/json" - }, - "display_in_profile_summary": { - "contentType": "application/json" - }, - "required": { - "contentType": "application/json" - }, - "editable_by_user": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The ID for the custom profile field.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "id": 9 - } - } - ] - } - } - } - } - } - } - }, - "/realm/user_settings_defaults": { - "patch": { - "operationId": "update-realm-user-settings-defaults", - "summary": "Update realm-level defaults of user settings", - "tags": ["server_and_organizations"], - "x-requires-administrator": true, - "description": "Change the [default values of settings][new-user-defaults] for new users\njoining the organization. Essentially all\n[personal preference settings](/api/update-settings) are supported.\n\nThis feature can be invaluable for customizing Zulip's default\nsettings for notifications or UI to be appropriate for how the\norganization is using Zulip. (Note that this only supports\npersonal preference settings, like when to send push\nnotifications or what emoji set to use, not profile or\nidentity settings that naturally should be different for each user).\n\nNote that this endpoint cannot, at present, be used to modify\nsettings for existing users in any way.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364)\nas we now have `web_font_size_px` and `web_line_height_percent`\nsettings for more control.\n\nNew in Zulip 5.0 (feature level 96). If any parameters sent in the\nrequest are not supported by this endpoint, an\n[`ignored_parameters_unsupported`][ignored-parameters] array will\nbe returned in the JSON success response.\n\n[new-user-defaults]: /help/configure-default-new-user-settings\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["left_side_userlist", "emojiset"] - } - } - ] - }, - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "starred_message_counts": { - "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n", - "type": "boolean", - "example": true - }, - "receives_typing_notifications": { - "description": "Whether the user is configured to receive typing notifications from other users.\nThe server will only deliver typing notifications events to users who for whom this\nis enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n", - "type": "boolean", - "example": true - }, - "web_suggest_update_timezone": { - "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n", - "type": "boolean", - "example": true - }, - "fluid_layout_width": { - "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n", - "type": "boolean", - "example": true - }, - "high_contrast_mode": { - "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n", - "type": "boolean", - "example": true - }, - "web_mark_read_on_scroll_policy": { - "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "web_channel_default_view": { - "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "web_font_size_px": { - "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", - "type": "integer", - "example": 14 - }, - "web_line_height_percent": { - "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", - "type": "integer", - "example": 122 - }, - "color_scheme": { - "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "enable_drafts_synchronization": { - "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n", - "type": "boolean", - "example": true - }, - "translate_emoticons": { - "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n", - "type": "boolean", - "example": true - }, - "display_emoji_reaction_users": { - "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting users, rather than\na count, for messages with few total reactions. The ideal cutoff may depend on\nthe space available for displaying reactions; the official web application\ndisplays names when 3 or fewer total reactions are present with this setting\nenabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n", - "type": "boolean", - "example": false - }, - "web_home_view": { - "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n", - "type": "string", - "example": "all_messages" - }, - "web_escape_navigates_to_home_view": { - "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called\n`escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107).\n", - "type": "boolean", - "example": true - }, - "left_side_userlist": { - "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n", - "type": "boolean", - "example": true - }, - "emojiset": { - "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n- \"google-blob\" - Google blobs\n", - "type": "string", - "example": "google" - }, - "demote_inactive_streams": { - "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "user_list_style": { - "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "web_animate_image_previews": { - "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images\nalways used to play in the message feed by default. This setting controls this\nbehaviour.\n", - "type": "string", - "enum": ["always", "on_hover", "never"], - "example": "on_hover" - }, - "web_stream_unreads_count_display_policy": { - "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 2 - }, - "hide_ai_features": { - "type": "boolean", - "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - }, - "web_left_sidebar_show_channel_folders": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n", - "example": true - }, - "web_left_sidebar_unreads_count_summary": { - "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n", - "type": "boolean", - "example": true - }, - "enable_stream_desktop_notifications": { - "description": "Enable visual desktop notifications for channel messages.\n", - "type": "boolean", - "example": true - }, - "enable_stream_email_notifications": { - "description": "Enable email notifications for channel messages.\n", - "type": "boolean", - "example": true - }, - "enable_stream_push_notifications": { - "description": "Enable mobile notifications for channel messages.\n", - "type": "boolean", - "example": true - }, - "enable_stream_audible_notifications": { - "description": "Enable audible desktop notifications for channel messages.\n", - "type": "boolean", - "example": true - }, - "notification_sound": { - "description": "Notification sound name.\n", - "type": "string", - "example": "ding" - }, - "enable_desktop_notifications": { - "description": "Enable visual desktop notifications for direct messages and @-mentions.\n", - "type": "boolean", - "example": true - }, - "enable_sounds": { - "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_desktop_notifications": { - "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_email_notifications": { - "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_push_notifications": { - "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": false - }, - "enable_followed_topic_audible_notifications": { - "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": false - }, - "email_notifications_batching_period_seconds": { - "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n", - "type": "integer", - "example": 120 - }, - "enable_offline_email_notifications": { - "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n", - "type": "boolean", - "example": true - }, - "enable_offline_push_notifications": { - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n", - "type": "boolean", - "example": true - }, - "enable_online_push_notifications": { - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n", - "type": "boolean", - "example": true - }, - "enable_digest_emails": { - "description": "Enable digest emails when the user is away.\n", - "type": "boolean", - "example": true - }, - "message_content_in_email_notifications": { - "description": "Include the message's content in email notifications for new messages.\n", - "type": "boolean", - "example": true - }, - "pm_content_in_desktop_notifications": { - "description": "Include content of direct messages in desktop notifications.\n", - "type": "boolean", - "example": true - }, - "wildcard_mentions_notify": { - "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_wildcard_mentions_notify": { - "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "desktop_icon_count_display": { - "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed\ntopics` option, renumbering the options to insert it in order.\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "realm_name_in_email_notifications_policy": { - "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "automatically_follow_topics_policy": { - "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "automatically_follow_topics_where_mentioned": { - "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n", - "type": "boolean", - "example": true - }, - "resolved_topic_notice_auto_read_policy": { - "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n", - "type": "string", - "enum": ["always", "except_followed", "never"], - "example": "except_followed" - }, - "presence_enabled": { - "description": "Display the presence status to other users when online.\n", - "type": "boolean", - "example": true - }, - "enter_sends": { - "description": "Whether pressing Enter in the compose box sends a message\n(or saves a message edit).\n", - "type": "boolean", - "example": true - }, - "twenty_four_hour_time": { - "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\n**Changes**: New in Zulip 5.0 (feature level 99).\nPreviously, this default was edited using the\n`default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint.\n", - "type": "boolean", - "example": true - }, - "send_private_typing_notifications": { - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "send_stream_typing_notifications": { - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "send_read_receipts": { - "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "email_address_visibility": { - "description": "The [policy][permission-level] for [which other users][help-email-visibility]\nin this organization can see the user's real email address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n", - "type": "integer", - "enum": [1, 2, 3, 4, 5], - "example": 1 - }, - "web_navigate_to_sent_message": { - "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n", - "type": "boolean", - "example": true - } - } - }, - "encoding": { - "starred_message_counts": { - "contentType": "application/json" - }, - "receives_typing_notifications": { - "contentType": "application/json" - }, - "web_suggest_update_timezone": { - "contentType": "application/json" - }, - "fluid_layout_width": { - "contentType": "application/json" - }, - "high_contrast_mode": { - "contentType": "application/json" - }, - "web_mark_read_on_scroll_policy": { - "contentType": "application/json" - }, - "web_channel_default_view": { - "contentType": "application/json" - }, - "web_font_size_px": { - "contentType": "application/json" - }, - "web_line_height_percent": { - "contentType": "application/json" - }, - "color_scheme": { - "contentType": "application/json" - }, - "enable_drafts_synchronization": { - "contentType": "application/json" - }, - "translate_emoticons": { - "contentType": "application/json" - }, - "display_emoji_reaction_users": { - "contentType": "application/json" - }, - "web_escape_navigates_to_home_view": { - "contentType": "application/json" - }, - "left_side_userlist": { - "contentType": "application/json" - }, - "demote_inactive_streams": { - "contentType": "application/json" - }, - "user_list_style": { - "contentType": "application/json" - }, - "web_stream_unreads_count_display_policy": { - "contentType": "application/json" - }, - "hide_ai_features": { - "contentType": "application/json" - }, - "web_left_sidebar_show_channel_folders": { - "contentType": "application/json" - }, - "web_left_sidebar_unreads_count_summary": { - "contentType": "application/json" - }, - "enable_stream_desktop_notifications": { - "contentType": "application/json" - }, - "enable_stream_email_notifications": { - "contentType": "application/json" - }, - "enable_stream_push_notifications": { - "contentType": "application/json" - }, - "enable_stream_audible_notifications": { - "contentType": "application/json" - }, - "enable_desktop_notifications": { - "contentType": "application/json" - }, - "enable_sounds": { - "contentType": "application/json" - }, - "enable_followed_topic_desktop_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_email_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_push_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_audible_notifications": { - "contentType": "application/json" - }, - "email_notifications_batching_period_seconds": { - "contentType": "application/json" - }, - "enable_offline_email_notifications": { - "contentType": "application/json" - }, - "enable_offline_push_notifications": { - "contentType": "application/json" - }, - "enable_online_push_notifications": { - "contentType": "application/json" - }, - "enable_digest_emails": { - "contentType": "application/json" - }, - "message_content_in_email_notifications": { - "contentType": "application/json" - }, - "pm_content_in_desktop_notifications": { - "contentType": "application/json" - }, - "wildcard_mentions_notify": { - "contentType": "application/json" - }, - "enable_followed_topic_wildcard_mentions_notify": { - "contentType": "application/json" - }, - "desktop_icon_count_display": { - "contentType": "application/json" - }, - "realm_name_in_email_notifications_policy": { - "contentType": "application/json" - }, - "automatically_follow_topics_policy": { - "contentType": "application/json" - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "contentType": "application/json" - }, - "automatically_follow_topics_where_mentioned": { - "contentType": "application/json" - }, - "presence_enabled": { - "contentType": "application/json" - }, - "enter_sends": { - "contentType": "application/json" - }, - "twenty_four_hour_time": { - "contentType": "application/json" - }, - "send_private_typing_notifications": { - "contentType": "application/json" - }, - "send_stream_typing_notifications": { - "contentType": "application/json" - }, - "send_read_receipts": { - "contentType": "application/json" - }, - "email_address_visibility": { - "contentType": "application/json" - }, - "web_navigate_to_sent_message": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SuccessIgnoredParameters" - } - } - } - }, - "/users/me/subscriptions/properties": { - "post": { - "operationId": "update-subscription-settings", - "summary": "Update subscription settings", - "tags": ["channels"], - "description": "This endpoint is used to update the user's personal settings for the\nchannels they are subscribed to, including muting, color, pinning, and\nper-channel notification settings.\n\n**Changes**: Prior to Zulip 5.0 (feature level 111), response\nobject included the `subscription_data` in the\nrequest. The endpoint now returns the more ergonomic\n[`ignored_parameters_unsupported`][ignored-parameters] array instead.\n\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "subscription_data": { - "description": "A list of objects that describe the changes that should be applied in\neach subscription. Each object represents a subscription, and must have\na `stream_id` key that identifies the channel, as well as the `property`\nbeing modified and its new `value`.\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "stream_id": { - "type": "integer", - "description": "The unique ID of a channel.\n" - }, - "property": { - "type": "string", - "enum": [ - "color", - "is_muted", - "in_home_view", - "pin_to_top", - "desktop_notifications", - "audible_notifications", - "push_notifications", - "email_notifications", - "wildcard_mentions_notify" - ], - "description": "One of the channel properties described below:\n\n- `\"color\"`: The hex value of the user's display color for the channel.\n\n- `\"is_muted\"`: Whether the channel is [muted](/help/mute-a-channel).
\n **Changes**: As of Zulip 6.0 (feature level 139), updating either\n `\"is_muted\"` or `\"in_home_view\"` generates two [subscription update\n events](/api/get-events#subscription-update), one for each property,\n that are sent to clients. Prior to this feature level, updating either\n property only generated a subscription update event for\n `\"in_home_view\"`.
\n Prior to Zulip 2.1.0, this feature was represented\n by the more confusingly named `\"in_home_view\"` (with the\n opposite value: `in_home_view=!is_muted`); for\n backwards-compatibility, modern Zulip still accepts that property.\n\n- `\"pin_to_top\"`: Whether to pin the channel at the top of the channel list.\n\n- `\"desktop_notifications\"`: Whether to show desktop notifications\n for all messages sent to the channel.\n\n- `\"audible_notifications\"`: Whether to play a sound\n notification for all messages sent to the channel.\n\n- `\"push_notifications\"`: Whether to trigger a mobile push\n notification for all messages sent to the channel.\n\n- `\"email_notifications\"`: Whether to trigger an email\n notification for all messages sent to the channel.\n\n- `\"wildcard_mentions_notify\"`: Whether wildcard mentions trigger\n notifications as though they were personal mentions in this channel.\n" - }, - "value": { - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "string" - } - ], - "description": "The new value of the property being modified.\n\nIf the property is `\"color\"`, then `value` is a string\nrepresenting the hex value of the user's display\ncolor for the channel. For all other above properties,\n`value` is a boolean.\n" - } - }, - "required": ["stream_id", "property", "value"], - "example": { - "stream_id": 2, - "property": "is_muted", - "value": true - } - }, - "example": [ - { - "stream_id": 1, - "property": "pin_to_top", - "value": true - }, - { - "stream_id": 3, - "property": "color", - "value": "#f00f00" - } - ] - } - }, - "required": ["subscription_data"] - }, - "encoding": { - "subscription_data": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SuccessIgnoredParameters" - } - } - } - }, - "/users/{email}": { - "get": { - "operationId": "get-user-by-email", - "summary": "Get a user by email", - "tags": ["users"], - "description": "Fetch details for a single user in the organization given a Zulip\nAPI email address.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by user ID](/api/get-user).\n\nFetching by user ID is generally recommended when possible,\nas a user might [change their email address](/help/change-your-email-address)\nor change their [email address visibility](/help/configure-email-visibility),\neither of which could change the client's ability to look them up by that\nemail address.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), the real email\naddress can be used in the `email` parameter and will fetch the target user's\ndata if and only if the target's email visibility setting permits the requester\nto see the email address.\nThe dummy email addresses of the form `user{id}@{realm.host}` still work, and\nwill now work for **all** users, via identifying them by the embedded user ID.\n\nNew in Zulip Server 4.0 (feature level 39).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": [""] - } - }, - { - "type": "exclude", - "parameters": { - "enum": [""] - }, - "description": "You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:\n" - } - ] - }, - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of the user to fetch. Two forms are supported:\n\n- The real email address of the user (`delivery_email`). The lookup will\n succeed if and only if the user exists and their email address visibility\n setting permits the client to see the email address.\n\n- The dummy Zulip API email address of the form `user{user_id}@{realm_host}`. This\n is identical to simply [getting user by ID](/api/get-user). If the server or\n realm change domains, the dummy email address used has to be adjustment to\n match the new realm domain. This is legacy behavior for\n backwards-compatibility, and will be removed in a future release.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), lookups by real email\naddress match the semantics of the target's email visibility setting and dummy\nemail addresses work for all users, independently of their email visibility\nsetting.\n\nPreviously, lookups were done only using the Zulip API email addresses.\n", - "schema": { - "type": "string" - }, - "example": "iago@zulip.com", - "required": true - }, - { - "$ref": "#/components/parameters/ClientGravatar" - }, - { - "$ref": "#/components/parameters/IncludeCustomProfileFields" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "user": { - "$ref": "#/components/schemas/User" - } - }, - "example": { - "msg": "", - "result": "success", - "user": { - "date_joined": "2019-10-20T07:50:53.729659+00:00", - "full_name": "King Hamlet", - "is_guest": false, - "profile_data": { - "4": { - "value": "0" - }, - "2": { - "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", - "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" - }, - "5": { - "value": "1900-01-01" - }, - "7": { - "value": "[11]" - }, - "6": { - "value": "https://blog.zulig.org" - }, - "1": { - "value": "+0-11-23-456-7890", - "rendered_value": "

+0-11-23-456-7890

" - }, - "8": { - "value": "zulipbot" - }, - "3": { - "rendered_value": "

Dark chocolate

", - "value": "Dark chocolate" - } - }, - "user_id": 10, - "is_bot": false, - "bot_type": null, - "timezone": "", - "is_admin": false, - "is_owner": false, - "role": 400, - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "is_active": true, - "email": "hamlet@zulip.com", - "delivery_email": null - } - } - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "update-user-by-email", - "summary": "Update a user by email", - "tags": ["users"], - "x-requires-administrator": true, - "description": "Administrative endpoint to update the details of another user in the organization by their email address.\nWorks the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their\nreal email address.\n\nThe requester needs to have permission to view the target user's real email address, subject to the\nuser's email address visibility setting. Otherwise, the dummy address of the format\n`user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{email}`.\n\n**Changes**: New in Zulip 10.0 (feature level 313).\n", - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "description": "The email address of the user, specified following the same rules as\n[`GET /users/{email}`](/api/get-user-by-email).\n", - "schema": { - "type": "string" - }, - "example": "hamlet@zulip.com" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/UpdateUser" - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Guests cannot be organization administrators", - "code": "BAD_REQUEST" - }, - "description": "A typical unsuccessful JSON response:\n" - } - ] - } - } - } - } - } - } - }, - "/users/{user_id}": { - "get": { - "operationId": "get-user", - "summary": "Get a user", - "tags": ["users"], - "description": "Fetch details for a single user in the organization.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by a user's Zulip API email](/api/get-user-by-email).\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": [""] - } - }, - { - "type": "exclude", - "parameters": { - "enum": [""] - }, - "description": "You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:\n" - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - }, - { - "$ref": "#/components/parameters/ClientGravatar" - }, - { - "$ref": "#/components/parameters/IncludeCustomProfileFields" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "user": { - "$ref": "#/components/schemas/User" - } - }, - "example": { - "msg": "", - "result": "success", - "user": { - "date_joined": "2019-10-20T07:50:53.729659+00:00", - "full_name": "King Hamlet", - "is_guest": false, - "profile_data": { - "4": { - "value": "0" - }, - "2": { - "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", - "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" - }, - "5": { - "value": "1900-01-01" - }, - "7": { - "value": "[11]" - }, - "6": { - "value": "https://blog.zulig.org" - }, - "1": { - "value": "+0-11-23-456-7890", - "rendered_value": "

+0-11-23-456-7890

" - }, - "8": { - "value": "zulipbot" - }, - "3": { - "rendered_value": "

Dark chocolate

", - "value": "Dark chocolate" - } - }, - "user_id": 10, - "is_bot": false, - "bot_type": null, - "timezone": "", - "is_admin": false, - "is_owner": false, - "role": 400, - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "is_active": true, - "email": "hamlet@zulip.com", - "delivery_email": null - } - } - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "update-user", - "summary": "Update a user", - "tags": ["users"], - "x-requires-administrator": true, - "description": "Administrative endpoint to update the details of another user in the organization.\n\nSupports everything an administrator can do to edit details of another\nuser's account, including editing full name,\n[role](/help/user-roles), and [custom profile\nfields](/help/custom-profile-fields).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/UpdateUser" - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Guests cannot be organization administrators", - "code": "BAD_REQUEST" - }, - "description": "A typical unsuccessful JSON response:\n" - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "deactivate-user", - "summary": "Deactivate a user", - "tags": ["users"], - "x-requires-administrator": true, - "description": "[Deactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "deactivation_notification_comment": { - "description": "If not `null`, requests that the deactivated user receive\na notification email about their account deactivation.\n\nIf not `\"\"`, encodes custom text written by the administrator\nto be included in the notification email.\n\n**Changes**: New in Zulip 5.0 (feature level 135).\n", - "type": "string", - "example": "Farewell!\n" - } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Cannot deactivate the only organization owner", - "result": "error" - }, - "description": "An example JSON error response when attempting to deactivate the only\norganization owner in an organization:\n" - } - ] - } - } - } - } - } - } - }, - "/realm/linkifiers": { - "get": { - "operationId": "get-linkifiers", - "summary": "Get linkifiers", - "tags": ["server_and_organizations"], - "description": "List all of an organization's configured\n[linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 54). On older versions,\na similar `GET /realm/filters` endpoint was available with each entry in\na `[pattern, url_format, id]` tuple format.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "linkifiers": { - "type": "array", - "description": "An ordered array of objects, where each object\ndescribes a linkifier.\n\nClients should always process linkifiers in the order given;\nthis is important if the realm has linkifiers with overlapping\npatterns. The order can be modified using [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "pattern": { - "type": "string", - "description": "The string regex pattern which represents the pattern that\nshould be linkified by this linkifier.\n" - }, - "url_template": { - "type": "string", - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant\nURL template to be used for linkifying matches.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the linkifier.\n" - } - } - } - } - }, - "example": { - "msg": "", - "linkifiers": [ - { - "pattern": "#(?P[0-9]+)", - "url_template": "https://github.com/zulip/zulip/issues/{id}", - "id": 1 - } - ], - "result": "success" - } - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "reorder-linkifiers", - "summary": "Reorder linkifiers", - "tags": ["server_and_organizations"], - "description": "Change the order that the regular expression patterns in the organization's\n[linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics.\nUseful when defining linkifiers with overlapping patterns.\n\n**Changes**: New in Zulip 8.0 (feature level 202). Before this feature level,\nlinkifiers were always processed in order by ID, which meant users would\nneed to delete and recreate them to reorder the list of linkifiers.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "ordered_linkifier_ids": { - "description": "A list of the IDs of all the linkifiers defined in this\norganization, in the desired new order.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [3, 2, 1, 5] - } - }, - "required": ["ordered_linkifier_ids"] - }, - "encoding": { - "ordered_linkifier_ids": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/realm/filters": { - "post": { - "operationId": "add-linkifier", - "summary": "Add a linkifier", - "tags": ["server_and_organizations"], - "description": "Configure [linkifiers](/help/add-a-custom-linkifier),\nregular expression patterns that are automatically linkified when they\nappear in messages and topics.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "pattern": { - "$ref": "#/components/schemas/LinkifierPattern" - }, - "url_template": { - "$ref": "#/components/schemas/LinkifierURLTemplate" - } - }, - "required": ["pattern", "url_template"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The numeric ID assigned to this filter.\n" - } - }, - "example": { - "id": 42, - "result": "success", - "msg": "" - } - } - ] - } - } - } - } - } - } - }, - "/realm/filters/{filter_id}": { - "delete": { - "operationId": "remove-linkifier", - "summary": "Remove a linkifier", - "tags": ["server_and_organizations"], - "description": "Remove [linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n", - "parameters": [ - { - "name": "filter_id", - "in": "path", - "description": "The ID of the linkifier that you want to remove.\n", - "schema": { - "type": "integer" - }, - "example": 43, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - }, - "patch": { - "operationId": "update-linkifier", - "summary": "Update a linkifier", - "tags": ["server_and_organizations"], - "description": "Update a [linkifier](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 57).\n", - "parameters": [ - { - "name": "filter_id", - "in": "path", - "description": "The ID of the linkifier that you want to update.\n", - "schema": { - "type": "integer" - }, - "example": 5, - "required": true - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "pattern": { - "$ref": "#/components/schemas/LinkifierPattern" - }, - "url_template": { - "$ref": "#/components/schemas/LinkifierURLTemplate" - } - }, - "required": ["pattern", "url_template"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/realm/playgrounds": { - "post": { - "operationId": "add-code-playground", - "summary": "Add a code playground", - "tags": ["server_and_organizations"], - "description": "Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was\nfixed in Zulip 4.0 (feature level 57).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The user-visible display name of the playground which can be\nused to pick the target playground, especially when multiple\nplayground options exist for that programming language.\n", - "type": "string", - "example": "Python playground" - }, - "pygments_language": { - "description": "The name of the Pygments language lexer for that\nprogramming language.\n", - "type": "string", - "example": "Python" - }, - "url_template": { - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template for the playground. The template should\ncontain exactly one variable named `code`, which determines how the\nextracted code should be substituted in the playground URL.\n\n**Changes**: New in Zulip 8.0 (feature level 196). This replaced the\n`url_prefix` parameter, which was used to construct URLs by just\nconcatenating `url_prefix` and `code`.\n", - "type": "string", - "example": "https://python.example.com?code={code}" - } - }, - "required": ["name", "pygments_language", "url_template"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The numeric ID assigned to this playground.\n" - } - }, - "example": { - "id": 1, - "result": "success", - "msg": "" - } - } - ] - } - } - } - } - } - } - }, - "/realm/playgrounds/{playground_id}": { - "delete": { - "operationId": "remove-code-playground", - "summary": "Remove a code playground", - "tags": ["server_and_organizations"], - "description": "Remove a [code playground](/help/code-blocks#code-playgrounds) previously\nconfigured for an organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n", - "parameters": [ - { - "name": "playground_id", - "in": "path", - "description": "The ID of the playground that you want to remove.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/export/realm": { - "get": { - "operationId": "get-realm-exports", - "summary": "Get all data exports", - "tags": ["server_and_organizations"], - "x-requires-administrator": true, - "description": "Fetch all the public and standard [data exports][export-data]\nof the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be fetched using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "exports": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains\ndetails about a data export of the organization.\n", - "items": { - "$ref": "#/components/schemas/RealmExport" - } - } - }, - "example": { - "exports": [ - { - "acting_user_id": 11, - "deleted_timestamp": null, - "export_type": 1, - "export_time": 1722243168.134179, - "export_url": "http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz", - "id": 323, - "failed_timestamp": null, - "pending": false - } - ], - "msg": "", - "result": "success" - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "export-realm", - "summary": "Create a data export", - "tags": ["server_and_organizations"], - "x-requires-administrator": true, - "description": "Create a public or a standard [data export][export-data] of the organization.\n\n!!! warn \"\"\n\n **Note**: If you're the administrator of a self-hosted installation,\n you may be looking for the documentation on [server data export and\n import][data-export] or [server backups][backups].\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be created using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server\n[data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export\n[backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "export_type": { - "description": "Whether to create a public or a standard data export.\n\n- 1 = Public data export.\n- 2 = Standard data export.\n\nIf not specified, defaults to 1.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nall export requests were public data exports.\n", - "type": "integer", - "enum": [1, 2], - "default": 1, - "example": 2 - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The ID of the data export created.\n\n**Changes**: New in Zulip 7.0 (feature level 182).\n" - } - }, - "example": { - "id": 1, - "result": "success", - "msg": "" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Please request a manual export from zulip-admin@example.com.", - "result": "error" - }, - "description": "An example JSON error response for when the data export\nexceeds the maximum allowed data export size.\n" - } - ] - } - } - } - } - } - } - }, - "/export/realm/consents": { - "get": { - "operationId": "get-realm-export-consents", - "summary": "Get data export consent state", - "tags": ["server_and_organizations"], - "x-requires-administrator": true, - "description": "Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data)\nfor their private data to be exported by organization administrators.\n\n**Changes**: New in Zulip 10.0 (feature level 295).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "export_consents": { - "type": "array", - "description": "An array of objects where each object contains a user ID and\nwhether the user has consented for their private data to be exported.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "user_id": { - "description": "The user ID.\n", - "type": "integer" - }, - "consented": { - "description": "Whether the user has consented for their private data export.\n", - "type": "boolean" - } - } - } - } - }, - "example": { - "export_consents": [ - { - "user_id": 11, - "consented": true - }, - { - "user_id": 6, - "consented": false - } - ], - "msg": "", - "result": "success" - } - } - ] - } - } - } - } - } - } - }, - "/invites": { - "get": { - "operationId": "get-invites", - "summary": "Get all invitations", - "tags": ["invites"], - "description": "Fetch all unexpired [invitations](/help/invite-new-users) (i.e. email\ninvitations and reusable invitation links) that can be managed by the user.\n\nNote that administrators can manage invitations that were created by other users.\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), non-admin users could\nonly create email invitations, and therefore the response would never include\nreusable invitation links for these users.\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "invites": { - "type": "array", - "description": "An array of objects, each representing a single unexpired\n[invitation](/help/invite-new-users).\n", - "items": { - "$ref": "#/components/schemas/Invite" - } - } - }, - "example": { - "result": "success", - "msg": "", - "invites": [ - { - "email": "example@zulip.com", - "expiry_date": null, - "id": 1, - "invited": 1710606654, - "invited_as": 200, - "invited_by_user_id": 9, - "notify_referrer_on_join": true, - "is_multiuse": false - }, - { - "expiry_date": 1711463862, - "id": 1, - "invited": 1710599862, - "invited_as": 400, - "invited_by_user_id": 9, - "is_multiuse": true, - "notify_referrer_on_join": true, - "link_url": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/" - } - ] - } - } - ] - } - } - } - } - } - }, - "post": { - "operationId": "send-invites", - "summary": "Send invitations", - "tags": ["invites"], - "description": "Send [invitations](/help/invite-new-users) to specified email addresses.\n\n**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `invite_expires_in_minutes`.\n\nIn Zulip 5.0 (feature level 117), added support for passing `null` as\nthe `invite_expires_in_days` parameter to request an invitation that never\nexpires.\n\nIn Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was\nadded which specified the number of days before the invitation would expire.\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "invitee_emails": { - "description": "The string containing the email addresses, separated by commas or\nnewlines, that will be sent an invitation.\n", - "type": "string", - "example": "example@zulip.com, logan@zulip.com" - }, - "invite_expires_in_minutes": { - "$ref": "#/components/schemas/InviteExpirationParameter" - }, - "invite_as": { - "$ref": "#/components/schemas/InviteRoleParameter" - }, - "stream_ids": { - "description": "A list containing the [IDs of the channels](/api/get-stream-id) that the\nnewly created user will be automatically subscribed to if the invitation\nis accepted, in addition to any default channels that the new user may\nbe subscribed to based on the `include_realm_default_subscriptions`\nparameter.\n\nRequested channels must either be default channels for the\norganization, or ones the acting user has permission to add\nsubscribers to.\n\nThis list must be empty if the current user has the unlikely\nconfiguration of being able to send invitations while lacking\npermission to [subscribe other users to channels][can-subscribe-others].\n\n**Changes**: Prior to Zulip 10.0 (feature level 342), default channels\nthat the acting user did not directly have permission to add\nsubscribers to would be rejected.\n\nBefore Zulip 7.0 (feature level 180), specifying `stream_ids` as an\nempty list resulted in an error.\n\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [1, 10] - }, - "group_ids": { - "description": "A list containing the [IDs of the user groups](/api/get-user-groups) that\nthe newly created user will be automatically added to if the invitation\nis accepted. If the list is empty, then the new user will not be\nadded to any user groups. The acting user must have permission to add users\nto the groups listed in this request.\n\n**Changes**: New in Zulip 10.0 (feature level 322).\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [] - }, - "include_realm_default_subscriptions": { - "description": "Boolean indicating whether the newly created user should be subscribed\nto the [default channels][default-channels] for the organization.\n\nNote that this parameter can be `true` even if the user creating the\ninvitation does not generally have permission to [subscribe other\nusers to channels][can-subscribe-others].\n\n**Changes**: New in Zulip 9.0 (feature level 261). Previous versions\nof Zulip behaved as though this parameter was always `false`; clients\nneeded to include the organization's default channels in the\n`stream_ids` parameter for a newly created user to be automatically\nsubscribed to them.\n\n[default-channels]: /help/set-default-channels-for-new-users\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", - "type": "boolean", - "default": false, - "example": false - }, - "notify_referrer_on_join": { - "description": "A boolean indicating whether the referrer would like to receive a\ndirect message from [notification\nbot](/help/configure-automated-notices) when a user account is created\nusing this invitation.\n\n**Changes**: New in Zulip 9.0 (feature level 267). Previously,\nreferrers always received such direct messages.\n", - "type": "boolean", - "example": false, - "default": true - }, - "welcome_message_custom_text": { - "description": "Custom message text, in Zulip Markdown format, to be sent by the\nWelcome Bot to new users that join the organization via this\ninvitation.\n\nMaximum length is 8000 characters.\n\nOnly organization administrators can use this feature; for other\nusers, the value is always `null`.\n\n- `null`: the organization's default `welcome_message_custom_text` is used.\n- Empty string: no Welcome Bot custom message is sent.\n- Otherwise, the provided string is the custom message.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", - "type": "string", - "nullable": true, - "example": "Welcome to Zulip! We're excited to have you on board." - } - }, - "required": ["invitee_emails", "stream_ids"] - }, - "encoding": { - "invite_expires_in_minutes": { - "contentType": "application/json" - }, - "stream_ids": { - "contentType": "application/json" - }, - "group_ids": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {} - }, - "example": { - "msg": "", - "result": "success" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/InvitationFailedError" - }, - { - "example": { - "result": "error", - "msg": "Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!", - "errors": [ - [ - "hamlet@zulip.com", - "Already has an account.", - false - ] - ], - "sent_invitations": true, - "license_limit_reached": false, - "daily_limit_reached": false, - "code": "INVITATION_FAILED" - }, - "description": "An example JSON error response for when some of the specified email addresses\nhave existing Zulip accounts.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Insufficient permission", - "result": "error" - }, - "description": "An example JSON error response for when the user doesn't have permission\nto send invitations.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "You must specify at least one email address.", - "result": "error" - }, - "description": "An example JSON error response for when no email address is specified.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid channel ID 11. No invites were sent.", - "result": "error" - }, - "description": "An example JSON error response for when any of the specified channels\ndoes not exist or the user does not have permission to access one of\nthe targeted channels.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "You do not have permission to subscribe other users to channels.", - "result": "error" - }, - "description": "An example JSON error response for when the user doesn't have permission\nto subscribe other users to channels and `stream_ids` is not empty.\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/invites/multiuse": { - "post": { - "operationId": "create-invite-link", - "summary": "Create a reusable invitation link", - "tags": ["invites"], - "description": "Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)\nwhich can be used to invite new users to the organization.\n\n**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin\nusers [with permission](/help/restrict-account-creation#change-who-can-send-invitations)\nto use this endpoint. Previously, it was restricted to administrators only.\n\nIn Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `invite_expires_in_minutes`.\n\nIn Zulip 5.0 (feature level 117), added support for passing `null` as\nthe `invite_expires_in_days` parameter to request an invitation that never\nexpires.\n\nIn Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was\nadded which specified the number of days before the invitation would expire.\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "invite_expires_in_minutes": { - "$ref": "#/components/schemas/InviteExpirationParameter" - }, - "invite_as": { - "$ref": "#/components/schemas/InviteRoleParameter" - }, - "stream_ids": { - "description": "A list containing the [IDs of the channels](/api/get-stream-id) that the\nnewly created user will be automatically subscribed to if the invitation\nis accepted, in addition to any default channels that the new user may\nbe subscribed to based on the `include_realm_default_subscriptions`\nparameter.\n\nRequested channels must either be default channels for the\norganization, or ones the acting user has permission to add\nsubscribers to.\n\nThis list must be empty if the current user has the unlikely\nconfiguration of being able to create reusable invitation links while\nlacking permission to [subscribe other users to\nchannels][can-subscribe-others].\n\n**Changes**: Prior to Zulip 10.0 (feature level 342), default channels\nthat the acting user did not directly have permission to add\nsubscribers to would be rejected.\n\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", - "type": "array", - "items": { - "type": "integer" - }, - "default": [], - "example": [1, 10] - }, - "group_ids": { - "description": "A list containing the [IDs of the user groups](/api/get-user-groups) that\nthe newly created user will be automatically added to if the invitation\nis accepted. If the list is empty, then the new user will not be\nadded to any user groups. The acting user must have permission to add users\nto the groups listed in this request.\n\n**Changes**: New in Zulip 10.0 (feature level 322).\n", - "type": "array", - "items": { - "type": "integer" - }, - "default": [], - "example": [] - }, - "include_realm_default_subscriptions": { - "description": "Boolean indicating whether the newly created user should be subscribed\nto the [default channels][default-channels] for the organization.\n\nNote that this parameter can be `true` even if the current user does\nnot generally have permission to [subscribe other users to\nchannels][can-subscribe-others].\n\n**Changes**: New in Zulip 9.0 (feature level 261). Previous versions\nof Zulip behaved as though this parameter was always `false`; clients\nneeded to include the organization's default channels in the\n`stream_ids` parameter for a newly created user to be automatically\nsubscribed to them.\n\n[default-channels]: /help/set-default-channels-for-new-users\n[can-subscribe-others]: /help/configure-who-can-invite-to-channels\n", - "type": "boolean", - "default": false, - "example": false - }, - "welcome_message_custom_text": { - "description": "Custom message text, in Zulip Markdown format, to be sent by the\nWelcome Bot to new users that join the organization via this\ninvitation.\n\nMaximum length is 8000 characters.\n\nOnly organization administrators can use this feature; for other\nusers, the value is always `null`.\n\n- `null`: the organization's default `welcome_message_custom_text` is used.\n- Empty string: no Welcome Bot custom message is sent.\n- Otherwise, the provided string is the custom message.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", - "type": "string", - "nullable": true, - "example": "Welcome to Zulip! We're excited to have you on board." - } - } - }, - "encoding": { - "invite_expires_in_minutes": { - "contentType": "application/json" - }, - "stream_ids": { - "contentType": "application/json" - }, - "group_ids": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "invite_link": { - "type": "string", - "description": "The URL of the [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)\nthat was created by this request.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "invite_link": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Insufficient permission", - "result": "error" - }, - "description": "An example JSON error response for when the user doesn't have permission\nto send invitations.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid channel ID 11. No invites were sent.", - "result": "error" - }, - "description": "An example JSON error response for when any of the specified channels\ndoes not exist or the user does not have permission to access one of\nthe targeted channels.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "You do not have permission to subscribe other users to channels.", - "result": "error" - }, - "description": "An example JSON error response for when the user doesn't have permission\nto subscribe other users to channels and `stream_ids` is not empty.\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/invites/{invite_id}": { - "delete": { - "operationId": "revoke-email-invite", - "summary": "Revoke an email invitation", - "tags": ["invites"], - "description": "Revoke an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n", - "parameters": [ - { - "name": "invite_id", - "in": "path", - "description": "The ID of the email invitation to be revoked.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "No such invitation", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for an invalid email invitation ID:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/invites/multiuse/{invite_id}": { - "delete": { - "operationId": "revoke-invite-link", - "summary": "Revoke a reusable invitation link", - "tags": ["invites"], - "description": "Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), only organization\nadministrators were able to create and revoke reusable invitation links.\n", - "parameters": [ - { - "name": "invite_id", - "in": "path", - "description": "The ID of the reusable invitation link to be revoked.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "No such invitation", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for an invalid invitation link ID:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Invitation has already been revoked", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for when the invitation link has already\nbeen revoked:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/invites/{invite_id}/resend": { - "post": { - "operationId": "resend-email-invite", - "summary": "Resend an email invitation", - "tags": ["invites"], - "description": "Resend an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only resend [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n", - "parameters": [ - { - "name": "invite_id", - "in": "path", - "description": "The ID of the email invitation to be resent.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "No such invitation", - "code": "BAD_REQUEST" - }, - "description": "A typical failed JSON response for an invalid email invitation ID:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/realm/test_welcome_bot_custom_message": { - "post": { - "operationId": "test-welcome-bot-custom-message", - "summary": "Test welcome bot custom message", - "tags": ["server_and_organizations"], - "x-requires-administrator": true, - "description": "Sends a test Welcome Bot custom message to the acting administrator.\nThis allows administrators to preview how the custom welcome message will\nappear when received by new users upon joining the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "welcome_message_custom_text": { - "description": "Custom message text, in Zulip Markdown format, to be used for\nthis test message.\n\nMaximum length is 8000 characters.\n", - "type": "string", - "maxLength": 8000, - "example": "Welcome to Zulip! We're excited to have you on board." - } - }, - "required": ["welcome_message_custom_text"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "message_id": { - "type": "integer", - "description": "The message_id of the test welcome bot custom message.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "message_id": 1 - } - } - ] - } - } - } - } - } - } - }, - "/register": { - "post": { - "operationId": "register-queue", - "summary": "Register an event queue", - "tags": ["real_time_events"], - "description": "This powerful endpoint can be used to register a Zulip \"event queue\"\n(subscribed to certain types of \"events\", or updates to the messages\nand other Zulip data the current user has access to), as well as to\nfetch the current state of that data.\n\n(`register` also powers the `call_on_each_event` Python API, and is\nintended primarily for complex applications for which the more convenient\n`call_on_each_event` API is insufficient).\n\nThis endpoint returns a `queue_id` and a `last_event_id`; these can be\nused in subsequent calls to the\n[\"events\" endpoint](/api/get-events) to request events from\nthe Zulip server using long-polling.\n\nThe server will queue events for up to 10 minutes of inactivity.\nAfter 10 minutes, your event queue will be garbage-collected. The\nserver will send `heartbeat` events every minute, which makes it easy\nto implement a robust client that does not miss events unless the\nclient loses network connectivity with the Zulip server for 10 minutes\nor longer.\n\nOnce the server garbage-collects your event queue, the server will\n[return an error](/api/get-events#bad_event_queue_id-errors)\nwith a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from\nthe event queue. Your software will need to handle that error\ncondition by re-initializing itself (e.g. this is what triggers your\nbrowser reloading the Zulip web app when your laptop comes back online\nafter being offline for more than 10 minutes).\n\nWhen prototyping with this API, we recommend first calling `register`\nwith no `event_types` parameter to see all the available data from all\nsupported event types. Before using your client in production, you\nshould set appropriate `event_types` and `fetch_event_types` filters\nso that your client only requests the data it needs. A few minutes\ndoing this often saves 90% of the total bandwidth and other resources\nconsumed by a client using this API.\n\nSee the [events system developer documentation][events-system-docs]\nif you need deeper details about how the Zulip event queue system\nworks, avoids clients needing to worry about large classes of\npotentially messy races, etc.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364)\nas we now have `web_font_size_px` and `web_line_height_percent`\nsettings for more control.\n\nBefore Zulip 7.0 (feature level 183), the\n`realm_community_topic_editing_limit_seconds` property\nwas returned by the response. It was removed because it\nhad not been in use since the realm setting\n`move_messages_within_stream_limit_seconds` was introduced\nin feature level 162.\n\nIn Zulip 7.0 (feature level 163), the realm setting\n`email_address_visibility` was removed. It was replaced by a [user\nsetting](/api/update-settings#parameter-email_address_visibility) with\na [realm user default][user-defaults], with the encoding of different\nvalues preserved. Clients can support all versions by supporting the\ncurrent API and treating every user as having the realm's\n`email_address_visibility` value.\n\n[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility\n[events-system-docs]: https://zulip.readthedocs.io/en/latest/subsystems/events-system.html\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["event_types"] - } - } - ] - }, - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "apply_markdown": { - "description": "Set to `true` if you would like the content to be rendered in HTML\nformat (otherwise the API will return the raw text that the user\nentered)\n", - "type": "boolean", - "default": false, - "example": true - }, - "client_gravatar": { - "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\nThe default value is `true` for authenticated requests and\n`false` for [unauthenticated\nrequests](/help/public-access-option). Passing `true` in\nan unauthenticated request is an error.\n\n**Changes**: Before Zulip 6.0 (feature level 149), this\nparameter was silently ignored and processed as though it\nwere `false` in unauthenticated requests.\n", - "type": "boolean", - "example": false - }, - "include_subscribers": { - "description": "Whether each returned channel object should include a `subscribers`\nfield containing a list of the user IDs of its subscribers.\n\nClient apps supporting organizations with many thousands of users\nshould not pass `true`, because the full subscriber matrix may be\nseveral megabytes of data. The `partial` value, combined with the\n`subscriber_count` and fetching subscribers for individual channels as\nneeded, is recommended to support client app features where channel\nsubscriber data is useful.\n\nIf a client passes `partial` for this parameter, the server may,\nfor some channels, return a subset of the channel's subscribers\nin the `partial_subscribers` field instead of the `subscribers` field,\nwhich always contains the complete set of subscribers.\n\nThe server guarantees that it will always return a `subscribers`\nfield for channels with fewer than 250 total subscribers. When\nreturning a `partial_subscribers` field, the server guarantees\nthat all bot users and users active within the last 14 days will\nbe included. For other cases, the server may use its discretion\nto determine which channels and users to include, balancing between\npayload size and usefulness of the data provided to the client.\n\nPassing `true` in an [unauthenticated\nrequest](/help/public-access-option) is an error.\n\n**Changes**: The `partial` value is new in Zulip 11.0 (feature level 412).\n\nBefore Zulip 6.0 (feature level 149), this parameter was silently\nignored and processed as though it were `false` in unauthenticated\nrequests.\n\nNew in Zulip 2.1.0.\n", - "type": "string", - "enum": ["true", "false", "partial"], - "default": "false", - "example": "true" - }, - "slim_presence": { - "description": "If `true`, the `presences` object returned in the response will be keyed\nby user ID and the entry for each user's presence data will be in the\nmodern format.\n\n**Changes**: New in Zulip 3.0 (no feature level; API unstable).\n", - "type": "boolean", - "default": false, - "example": true - }, - "presence_history_limit_days": { - "description": "Limits how far back in time to fetch user presence data. If not specified,\ndefaults to 14 days. A value of N means that the oldest presence data\nfetched will be from at most N days ago.\n\n**Changes**: New in Zulip 10.0 (feature level 288).\n", - "type": "integer", - "example": 365 - }, - "event_types": { - "$ref": "#/components/schemas/Event_types" - }, - "all_public_streams": { - "$ref": "#/components/schemas/AllPublicChannels" - }, - "client_capabilities": { - "description": "Dictionary containing details on features the client supports that are\nrelevant to the format of responses sent by the server.\n\n- `notification_settings_null`: Boolean for whether the\n client can handle the current API with `null` values for\n channel-level notification settings (which means the channel\n is not customized and should inherit the user's global\n notification settings for channel messages).\n
\n **Changes**: New in Zulip 2.1.0. In earlier Zulip releases,\n channel-level notification settings were simple booleans.\n\n- `bulk_message_deletion`: Boolean for whether the client's\n handler for the `delete_message` event type has been\n updated to process the new bulk format (with a\n `message_ids`, rather than a singleton `message_id`).\n Otherwise, the server will send `delete_message` events\n in a loop.\n
\n **Changes**: New in Zulip 3.0 (feature level 13). This\n capability is for backwards-compatibility; it will be\n required in a future server release.\n\n- `user_avatar_url_field_optional`: Boolean for whether the\n client required avatar URLs for all users, or supports\n using `GET /avatar/{user_id}` to access user avatars. If the\n client has this capability, the server may skip sending a\n `avatar_url` field in the `realm_user` at its sole discretion\n to optimize network performance. This is an important optimization\n in organizations with 10,000s of users.\n
\n **Changes**: New in Zulip 3.0 (feature level 18).\n\n- `stream_typing_notifications`: Boolean for whether the client\n supports channel typing notifications.\n
\n **Changes**: New in Zulip 4.0 (feature level 58). This capability is\n for backwards-compatibility; it will be required in a\n future server release.\n\n- `user_settings_object`: Boolean for whether the client supports the modern\n `user_settings` event type. If false, the server will additionally send the\n legacy `update_global_notifications` and `update_display_settings` event\n types.\n
\n **Changes**: New in Zulip 5.0 (feature level 89). This capability is for\n backwards-compatibility; it will be removed in a future server release.\n Because the feature level 89 API changes were merged together, clients can\n safely make a request with this client capability and also request all three\n event types (`user_settings`, `update_display_settings`,\n `update_global_notifications`), and get exactly one copy of settings data on\n any server version. Clients can then use the `zulip_feature_level` in the\n `/register` response or the presence/absence of a `user_settings` key to\n determine where to look for the data.\n\n- `linkifier_url_template`: Boolean for whether the client accepts\n [linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant\n URL templates for linkifying matches. If false or unset, then the\n `realm_linkifiers` array in the `/register` response will be empty\n if present, and no `realm_linkifiers` [events][events-linkifiers]\n will be sent to the client.\n
\n **Changes**: New in Zulip 7.0 (feature level 176). This capability\n is for backwards-compatibility.\n\n- `user_list_incomplete`: Boolean for whether the client supports not having an\n incomplete user database. If true, then the `realm_users` array in the `register`\n response will not include data for inaccessible users and clients of guest users will\n not receive `realm_user op:add` events for newly created users that are not accessible\n to the current user.\n
\n **Changes**: New in Zulip 8.0 (feature level 232). This\n capability is for backwards-compatibility.\n\n- `include_deactivated_groups`: Boolean for whether the client can handle\n deactivated user groups by themselves. If false, then the `realm_user_groups`\n array in the `/register` response will only include active groups, clients\n will receive a `remove` event instead of `update` event when a group is\n deactivated and no `update` event will be sent to the client if a deactivated\n user group is renamed.\n
\n **Changes**: New in Zulip 10.0 (feature level 294). This\n capability is for backwards-compatibility.\n\n- `archived_channels`: Boolean for whether the client supports processing\n [archived channels](/help/archive-a-channel) in the `stream` and\n `subscription` event types. If `false`, the server will not include data\n related to archived channels in the `register` response or in events.\n
\n **Changes**: New in Zulip 10.0 (feature level 315). This allows clients to\n access archived channels, without breaking backwards-compatibility for\n existing clients.\n\n- `empty_topic_name`: Boolean for whether the client supports processing\n the empty string as a topic name. Clients not declaring this capability\n will be sent the value of `realm_empty_topic_display_name` found in the\n [POST /register](/api/register-queue) response instead of the empty string\n wherever topic names appear in the register response or events involving\n topic names.\n
\n **Changes**: New in Zulip 10.0 (feature level 334). Previously,\n the empty string was not a valid topic name.\n\n- `simplified_presence_events`: Boolean for whether the client supports\n receiving the [`presence` event type](/api/get-events#presence) with\n user presence data in the modern format. If true, the server will\n send these events with the `presences` field that has the user presence\n data in the modern format. Otherwise, these event will contain fields\n with legacy format user presence data.\n
\n **Changes**: New in Zulip 11.0 (feature level 419).\n\n[help-linkifiers]: /help/add-a-custom-linkifier\n[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html\n[events-linkifiers]: /api/get-events#realm_linkifiers\n", - "type": "object", - "example": { - "notification_settings_null": true - } - }, - "fetch_event_types": { - "description": "Same as the `event_types` parameter except that the values in\n`fetch_event_types` are used to fetch initial data. If\n`fetch_event_types` is not provided, `event_types` is used and if\n`event_types` is not provided, this parameter defaults to `null`.\n\nEvent types not supported by the server are ignored, in order to simplify\nthe implementation of client apps that support multiple server versions.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["message"] - }, - "narrow": { - "$ref": "#/components/schemas/Narrow" - } - } - }, - "encoding": { - "apply_markdown": { - "contentType": "application/json" - }, - "client_gravatar": { - "contentType": "application/json" - }, - "slim_presence": { - "contentType": "application/json" - }, - "event_types": { - "contentType": "application/json" - }, - "all_public_streams": { - "contentType": "application/json" - }, - "client_capabilities": { - "contentType": "application/json" - }, - "fetch_event_types": { - "contentType": "application/json" - }, - "narrow": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "queue_id": { - "type": "string", - "nullable": true, - "description": "The ID of the queue that has been allocated for your client.\n\nWill be `null` only for unauthenticated access in realms that have\nenabled the [public access option](/help/public-access-option).\n" - }, - "last_event_id": { - "type": "integer", - "description": "The initial value of `last_event_id` to pass to `GET /api/v1/events`.\n" - }, - "zulip_feature_level": { - "type": "integer", - "description": "The server's current [Zulip feature level](/api/changelog).\n\n**Changes**: As of Zulip 3.0 (feature level 3), this is always present\nin the endpoint's response. Previously, it was only present if\n`event_types` included `zulip_version`.\n\nNew in Zulip 3.0 (feature level 1).\n" - }, - "zulip_version": { - "type": "string", - "description": "The server's version number. This is often a release version number,\nlike `2.1.7`. But for a server running a [version from Git][git-release],\nit will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.\n\n**Changes**: As of Zulip 3.0 (feature level 3), this is always present\nin the endpoint's response. Previously, it was only present if\n`event_types` included `zulip_version`.\n\n[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions\n" - }, - "zulip_merge_base": { - "type": "string", - "description": "The `git merge-base` between `zulip_version` and official branches\nin the public\n[Zulip server and web app repository](https://github.com/zulip/zulip),\nin the same format as `zulip_version`. This will equal\n`zulip_version` if the server is not running a fork of the Zulip server.\n\nThis will be `\"\"` if the server does not know its `merge-base`.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" - }, - "alert_words": { - "type": "array", - "description": "Present if `alert_words` is present in `fetch_event_types`.\n\nAn array of strings, each an [alert word](/help/dm-mention-alert-notifications#alert-words)\nthat the current user has configured.\n", - "items": { - "type": "string" - } - }, - "custom_profile_fields": { - "type": "array", - "description": "Present if `custom_profile_fields` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary contains the\ndetails of a single custom profile field that is available to users\nin this Zulip organization. This must be combined with the custom profile\nfield values on individual user objects to display users' profiles.\n", - "items": { - "$ref": "#/components/schemas/CustomProfileField" - } - }, - "custom_profile_field_types": { - "type": "object", - "description": "Present if `custom_profile_fields` is present in `fetch_event_types`.\n\nAn array of objects; each object describes a type of custom profile field\nthat could be configured on this Zulip server. Each custom profile type\nhas an ID and the `type` property of a custom profile field is equal\nto one of these IDs.\n\nThis attribute is only useful for clients containing UI for changing\nthe set of configured custom profile fields in a Zulip organization.\n", - "additionalProperties": { - "type": "object", - "description": "`{FIELD_TYPE}`: Dictionary which contains the details\nof the field type with the field type as the name of the\nproperty itself. The current supported field types are as follows:\n\n- `SHORT_TEXT`\n- `LONG_TEXT`\n- `DATE` for date-based fields.\n- `SELECT` for a list of options.\n- `URL` for links.\n- `EXTERNAL_ACCOUNT` for external accounts.\n- `USER` for selecting a user for the field.\n- `PRONOUNS` for a short text field with convenient typeahead for one's preferred pronouns.\n\n**Changes**: `PRONOUNS` type added in Zulip 6.0 (feature level 151).\n", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "The ID of the custom profile field type.\n" - }, - "name": { - "type": "string", - "description": "The name of the custom profile field type.\n" - } - } - } - }, - "realm_date_created": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe UNIX timestamp (UTC) for when the organization was\ncreated.\n\n**Changes**: New in Zulip 8.0 (feature level 203).\n" - }, - "demo_organization_scheduled_deletion_date": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`,\nand the realm is a demo organization.\n\nThe UNIX timestamp (UTC) when the demo organization will be\nautomatically deleted. Clients should use this to display a\nprominent warning to the user that the organization will be\ndeleted at the indicated time.\n\n**Changes**: New in Zulip 5.0 (feature level 94).\n" - }, - "drafts": { - "type": "array", - "description": "An array containing draft objects for the user. These drafts are being\nstored on the backend for the purpose of syncing across devices. This\narray will be empty if `enable_drafts_synchronization` is set to `false`.\n", - "items": { - "$ref": "#/components/schemas/Draft" - } - }, - "onboarding_steps": { - "type": "array", - "description": "Present if `onboarding_steps` is present in `fetch_event_types`.\n\nAn array of dictionaries, where each dictionary contains details about\na single onboarding step that should be shown to the user.\n\nWe expect that only official Zulip clients will interact with this data.\n\n**Changes**: Before Zulip 8.0 (feature level 233), this array was named\n`hotspots`. Prior to this feature level, one-time notice onboarding\nsteps were not supported, and the `type` field in these objects did not\nexist as all onboarding steps were implicitly hotspots.\n", - "items": { - "$ref": "#/components/schemas/OnboardingStep" - } - }, - "navigation_tour_video_url": { - "type": "string", - "nullable": true, - "description": "Present if `onboarding_steps` is present in `fetch_event_types`.\n\nURL of the navigation tour video to display to new users during\nonboarding. If `null`, the onboarding video experience is disabled.\n\n**Changes**: New in Zulip 10.0 (feature level 369).\n" - }, - "max_message_id": { - "type": "integer", - "deprecated": true, - "description": "Present if `message` is present in `fetch_event_types`.\n\nThe highest message ID among all messages the user has received as of the\nmoment of this request.\n\n**Deprecated**: This field may be removed in future versions as it no\nlonger has a clear purpose. Clients wishing to fetch the latest messages\nshould pass `\"anchor\": \"latest\"` to `GET /messages`.\n" - }, - "max_reminder_note_length": { - "type": "integer", - "description": "The maximum allowed length for a reminder note.\n\n**Changes**: New in Zulip 11.0 (feature level 415).\n" - }, - "max_stream_name_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel name, in Unicode code\npoints. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis required `stream` in `fetch_event_types`, was called\n`stream_name_max_length`, and always had a value of 60.\n" - }, - "max_stream_description_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel description, in Unicode\ncode points. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis required `stream` in `fetch_event_types`, was called\n`stream_description_max_length`, and always had a value of 1024.\n" - }, - "max_channel_folder_name_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel folder name, in Unicode\ncode points. Clients should use this property rather than hardcoding\nfield sizes.\n\n**Changes**: New in Zulip 11.0 (feature level 410). Clients should use\n60 as a fallback value on previous feature levels.\n" - }, - "max_channel_folder_description_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a channel folder description, in\nUnicode code points. Clients should use this property rather than\nhardcoding field sizes.\n\n**Changes**: New in Zulip 11.0 (feature level 410). Clients should use\n1024 as a fallback value on previous feature levels.\n" - }, - "max_topic_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a topic, in Unicode code points.\nClients should use this property rather than hardcoding field\nsizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis property always had a value of 60.\n" - }, - "max_message_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum allowed length for a message, in Unicode code points.\nClients should use this property rather than hardcoding field\nsizes.\n\n**Changes**: New in Zulip 4.0 (feature level 53). Previously,\nthis property always had a value of 10000.\n" - }, - "server_min_deactivated_realm_deletion_days": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe minimum permitted number of days before full data deletion\n(users, channels, messages, etc.) of a deactivated organization.\nIf `null`, then a deactivated organization's data can be\ndeleted immediately.\n\n**Changes**: New in Zulip 10.0 (feature level 332)\n" - }, - "server_max_deactivated_realm_deletion_days": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum permitted number of days before full data deletion\n(users, channels, messages, etc.) of a deactivated organization.\nIf `null`, then a deactivated organization's data can be\nretained indefinitely.\n\n**Changes**: New in Zulip 10.0 (feature level 332).\n" - }, - "server_presence_ping_interval_seconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing the [presence](/api/get-presence) system,\nthe time interval the client should use for sending presence requests\nto the server (and thus receive presence updates from the server).\n\nIt is important for presence implementations to use both this and\n`server_presence_offline_threshold_seconds` correctly, so that a Zulip\nserver can change these values to manage the trade-off between load and\nfreshness of presence data.\n\n**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 60\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip mobile apps prior to this parameter being introduced.\n" - }, - "server_presence_offline_threshold_seconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nHow old a presence timestamp for a given user can be before the user\nshould be displayed as offline by clients displaying Zulip presence\ndata. See the related `server_presence_ping_interval_seconds` for details.\n\n**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 140\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip client apps prior to this parameter being introduced.\n" - }, - "server_typing_started_expiry_period_milliseconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should wait\nfor additional [typing start](/api/get-events#typing-start) events from\nthe server before removing an active typing indicator.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 15000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" - }, - "server_typing_stopped_wait_period_milliseconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should wait\nwhen a user stops interacting with the compose UI before sending a stop\nnotification to the server.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 5000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" - }, - "server_typing_started_wait_period_milliseconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nFor clients implementing [typing notifications](/api/set-typing-status)\nprotocol, the time interval in milliseconds that the client should use\nto send regular start notifications to the server to indicate that the\nuser is still actively interacting with the compose UI.\n\n**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 10000\nfor older Zulip servers, since that's the value that was hardcoded in the\nZulip apps prior to this parameter being introduced.\n" - }, - "scheduled_messages": { - "type": "array", - "description": "Present if `scheduled_messages` is present in `fetch_event_types`.\n\nAn array of all undelivered scheduled messages by the user.\n\n**Changes**: New in Zulip 7.0 (feature level 179).\n", - "items": { - "$ref": "#/components/schemas/ScheduledMessage" - } - }, - "reminders": { - "type": "array", - "description": "Present if `reminders` is present in `fetch_event_types`.\n\nAn array of all undelivered reminders scheduled by the user.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n", - "items": { - "$ref": "#/components/schemas/ScheduledMessage" - } - }, - "muted_topics": { - "type": "array", - "deprecated": true, - "description": "Present if `muted_topics` is present in `fetch_event_types`.\n\nArray of tuples, where each tuple describes a muted topic.\nThe first element of the tuple is the channel name in which the topic\nhas to be muted, the second element is the topic name to be muted\nand the third element is an integer UNIX timestamp representing\nwhen the topic was muted.\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting\nwith this version, `muted_topics` will only be present in the\nresponse if the `user_topic` object, which generalizes and replaces\nthis field, is not explicitly requested via `fetch_event_types`.\n\nBefore Zulip 3.0 (feature level 1), the `muted_topics`\narray objects were 2-item tuples and did not include the timestamp\ninformation for when the topic was muted.\n", - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ] - } - } - }, - "muted_users": { - "type": "array", - "description": "Present if `muted_users` is present in `fetch_event_types`.\n\nA list of dictionaries where each dictionary describes\na [muted user](/api/mute-user).\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the user ID and timestamp of a muted user.\n", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the muted user.\n" - }, - "timestamp": { - "type": "integer", - "description": "An integer UNIX timestamp representing when the user was muted.\n" - } - } - } - }, - "presences": { - "type": "object", - "description": "Present if `presence` is present in `fetch_event_types`.\n\nA dictionary where each entry describes the presence details of a\nuser in the Zulip organization.\n\nThe format of the entry (modern or legacy) depends on the value of\n[`slim_presence`](#parameter-slim_presence).\n\nUsers who have been offline for multiple weeks may not appear in this object.\n", - "additionalProperties": { - "type": "object", - "description": "Will be one of these two formats (modern or legacy) for user\npresence data:\n", - "oneOf": [ - { - "$ref": "#/components/schemas/ModernPresenceFormat" - }, - { - "type": "object", - "description": "`{user_email}`: Presence data (legacy format) for the user with\nthe specified Zulip API email.\n", - "additionalProperties": { - "$ref": "#/components/schemas/LegacyPresenceFormat" - } - } - ] - } - }, - "presence_last_update_id": { - "type": "integer", - "description": "Present if `presence` is present in `fetch_event_types`.\n\nProvides the `last_update_id` value of the latest presence data fetched by\nthe server and included in the response in `presences`. This can be used\nas the value of the `presence_last_update_id` parameter when polling\nfor presence data at the [/users/me/presence](/api/update-presence) endpoint\nto tell the server to only fetch the relevant newer data in order to skip\nredundant already-known presence information.\n\n**Changes**: New in Zulip 9.0 (feature level 263).\n" - }, - "server_timestamp": { - "type": "number", - "description": "Present if `presence` is present in `fetch_event_types`.\n\nThe time when the server fetched the\n`presences` data included in the response.\nMatches the similar field in presence\nresponses.\n\n**Changes**: New in Zulip 5.0 (feature level 70).\n" - }, - "realm_domains": { - "type": "array", - "description": "Present if `realm_domains` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a domain within\nwhich users can join the organization without and invitation.\n", - "items": { - "$ref": "#/components/schemas/RealmDomain" - } - }, - "realm_emoji": { - "description": "Present if `realm_emoji` is present in `fetch_event_types`.\n\nA dictionary of objects where each object describes a custom\nemoji that has been uploaded in this Zulip organization.\n", - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/RealmEmoji" - } - }, - "realm_linkifiers": { - "type": "array", - "description": "Present if `realm_linkifiers` is present in `fetch_event_types`.\n\nAn ordered array of objects where each object describes a single\n[linkifier](/help/add-a-custom-linkifier).\n\nThe order of the array reflects the order that each\nlinkifier should be processed when linkifying messages\nand topics. By default, new linkifiers are ordered\nlast. This order can be modified with [`PATCH\n/realm/linkifiers`](/api/reorder-linkifiers).\n\nClients will receive an empty array unless the event queue is\nregistered with the client capability `{\"linkifier_url_template\": true}`.\nSee [`client_capabilities`](/api/register-queue#parameter-client_capabilities)\nparameter for how this can be specified.\n\n**Changes**: Before Zulip 7.0 (feature level 176), the\n`linkifier_url_template` client capability was not required. The\nrequirement was added because linkifiers were updated to contain\na URL template instead of a URL format string, which was a not\nbackwards-compatible change.\n\nNew in Zulip 4.0 (feature level 54). Clients can access this data for\nservers on earlier feature levels via the legacy `realm_filters` property.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "pattern": { - "type": "string", - "description": "The [Python regular expression](https://docs.python.org/3/howto/regex.html)\npattern which represents the pattern that should be linkified on matching.\n" - }, - "url_template": { - "type": "string", - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL\ntemplate with which the pattern matching string should be linkified.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,\nwhich contained a URL format string.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the linkifier.\n" - } - } - } - }, - "realm_filters": { - "type": "array", - "deprecated": true, - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "integer" - }, - { - "type": "string" - } - ] - } - }, - "description": "Legacy property for [linkifiers](/help/add-a-custom-linkifier).\nPresent if `realm_filters` is present in `fetch_event_types`.\n\nWhen present, this is always an empty array.\n\n**Changes**: Prior to Zulip 7.0 (feature level 176), this was\nan array of tuples, where each tuple described a linkifier. The first\nelement of the tuple was a string regex pattern which represented the\npattern to be linkified on matching, for example `\"#(?P[123])\"`.\nThe second element was a URL format string that the pattern should be\nlinkified with. A URL format string for the above example would be\n`\"https://realm.com/my_realm_filter/%(id)s\"`. And the third element\nwas the ID of the realm filter.\n\n**Deprecated** in Zulip 4.0 (feature level 54), replaced by the\n`realm_linkifiers` key.\n" - }, - "realm_playgrounds": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RealmPlayground" - }, - "description": "Present if `realm_playgrounds` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a\n[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n" - }, - "realm_user_groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/UserGroup" - }, - "description": "Present if `realm_user_groups` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a\n[user group](/help/user-groups) in the Zulip organization.\n\nDeactivated groups will only be included if `include_deactivated_groups`\nclient capability is set to `true`.\n\n**Changes**: Prior to Zulip 10.0 (feature level 294), deactivated\ngroups were included for all the clients.\n" - }, - "realm_bots": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Bot" - }, - "description": "Present if `realm_bot` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a bot that the\ncurrent user can administer. If the current user is an organization\nadministrator, this will include all bots in the organization. Otherwise,\nit will only include bots owned by the user (either because the user created\nthe bot or an administrator transferred the bot's ownership to the user).\n" - }, - "realm_embedded_bots": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of an embedded bot. Embedded bots are an experimental\nfeature not enabled in production yet.\n", - "properties": { - "name": { - "type": "string", - "description": "The name of the bot.\n" - }, - "config": { - "$ref": "#/components/schemas/BotConfiguration" - } - } - }, - "description": "Present if `realm_embedded_bots` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes an type of embedded\nbot that is available to be configured on this Zulip server.\n\nClients only need these data if they contain UI for creating or administering bots.\n" - }, - "realm_incoming_webhook_bots": { - "description": "Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes a type of incoming webhook\nintegration that is available to be configured on this Zulip server.\n\nClients only need these data if they contain UI for creating or administering bots.\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of the bot.\n", - "properties": { - "name": { - "type": "string", - "description": "A machine-readable unique name identifying the integration, all-lower-case without\nspaces.\n" - }, - "display_name": { - "type": "string", - "description": "A human-readable display name identifying the integration that this bot implements,\nintended to be used in menus for selecting which integration to create.\n\n**Changes**: New in Zulip 8.0 (feature level 207).\n" - }, - "all_event_types": { - "type": "array", - "items": { - "type": "string" - }, - "nullable": true, - "description": "For incoming webhook integrations that support the Zulip server filtering incoming\nevents, the list of event types supported by it.\n\nA null value will be present if this incoming webhook integration doesn't support\nsuch filtering.\n\n**Changes**: New in Zulip 8.0 (feature level 207).\n" - }, - "config_options": { - "$ref": "#/components/schemas/WebhookConfigOption" - }, - "url_options": { - "$ref": "#/components/schemas/WebhookUrlOption" - } - } - } - }, - "recent_private_conversations": { - "description": "Present if `recent_private_conversations` is present in `fetch_event_types`.\n\nAn array of dictionaries containing data on all direct message and group direct message\nconversations that the user has received (or sent) messages in, organized by\nconversation. This data set is designed to support UI elements such as the\n\"Direct messages\" widget in the web application showing recent direct message\nconversations that the user has participated in.\n\n\"Recent\" is defined as the server's discretion; the original implementation\ninterpreted that as \"the 1000 most recent direct messages the user received\".\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "description": "Object describing a single recent direct conversation in the user's history.\n", - "properties": { - "max_message_id": { - "type": "integer", - "description": "The highest message ID of the conversation, intended to support sorting\nthe conversations by recency.\n" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "The list of users other than the current user in the direct message\nconversation. This will be an empty list for direct messages sent to\noneself.\n" - } - } - } - }, - "navigation_views": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NavigationView" - }, - "description": "Present if `navigation_views` is present in `fetch_event_types`.\nAn array of dictionaries containing data on all of the current user's\nnavigation views.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" - }, - "saved_snippets": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SavedSnippet" - }, - "description": "Present if `saved_snippets` is present in `fetch_event_types`.\n\nAn array of dictionaries containing data on all of the current user's\nsaved snippets.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" - }, - "subscriptions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Subscription" - }, - "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes the properties\nof a channel the user is subscribed to (as well as that user's\npersonal per-channel settings).\n\n**Changes**: Removed `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n" - }, - "unsubscribed": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Subscription" - }, - "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes one of the\nchannels the user has unsubscribed from but was previously subscribed to\nalong with the subscription details.\n\nUnlike `never_subscribed`, the user might have messages in their personal\nmessage history that were sent to these channels.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), if a user was\nin `can_administer_channel_group` of a channel that they had\nunsubscribed from, but not an organization administrator, the channel\nin question would not be part of this array.\n\nRemoved `email_address` field from the dictionary\nin Zulip 8.0 (feature level 226).\n\nRemoved `role` field from the dictionary\nin Zulip 6.0 (feature level 133).\n" - }, - "never_subscribed": { - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/BasicChannelBase" - }, - { - "additionalProperties": false, - "properties": { - "stream_id": {}, - "name": {}, - "is_archived": {}, - "description": {}, - "date_created": {}, - "creator_id": { - "nullable": true - }, - "invite_only": {}, - "rendered_description": {}, - "is_web_public": {}, - "stream_post_policy": {}, - "message_retention_days": { - "nullable": true - }, - "history_public_to_subscribers": {}, - "topics_policy": {}, - "first_message_id": { - "nullable": true - }, - "folder_id": { - "nullable": true - }, - "is_recently_active": {}, - "is_announcement_only": {}, - "can_add_subscribers_group": {}, - "can_remove_subscribers_group": {}, - "can_administer_channel_group": {}, - "can_delete_any_message_group": {}, - "can_delete_own_message_group": {}, - "can_move_messages_out_of_channel_group": {}, - "can_move_messages_within_channel_group": {}, - "can_send_message_group": {}, - "can_subscribe_group": {}, - "can_resolve_topics_group": {}, - "subscriber_count": {}, - "stream_weekly_traffic": { - "type": "integer", - "nullable": true, - "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, the channel was recently created and there is\ninsufficient data to estimate the average traffic.\n" - }, - "subscribers": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A list of user IDs of users who are subscribed\nto the channel. Included only if `include_subscribers` is `true`.\n\nIf a user is not allowed to know the subscribers for\na channel, we will send an empty array. API authors\nshould use other data to determine whether users like\nguest users are forbidden to know the subscribers.\n" - }, - "partial_subscribers": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "If [`include_subscribers=\"partial\"`](/api/get-subscriptions#parameter-include_subscribers)\nwas requested, the server may, at its discretion, send a\n`partial_subscribers` list rather than a `subscribers` list\nfor channels with a large number of subscribers.\n\nThe `partial_subscribers` list contains an arbitrary\nsubset of the channel's subscribers that is guaranteed\nto include all bot user subscribers as well as all\nusers who have been active in the last 14 days, but\notherwise can be chosen arbitrarily by the server.\n\nIf a user is not allowed to know the subscribers for\na channel, we will send an empty array. API authors\nshould use other data to determine whether users like\nguest users are forbidden to know the subscribers.\n\n**Changes**: New in Zulip 11.0 (feature level 412).\n" - } - } - } - ] - }, - "description": "Present if `subscription` is present in `fetch_event_types`.\n\nA array of dictionaries where each dictionary describes one of the\nchannels that is visible to the user and the user has never been subscribed\nto.\n\nImportant for clients containing UI where one can browse channels to subscribe\nto.\n\n**Changes**: Before Zulip 10.0 (feature level 362), archived channels did\nnot appear in this list, even if the `archived_channels` [client\ncapability][client-capabilities] was declared by the client.\n\nPrior to Zulip 10.0 (feature level 349), if a user was\nin `can_administer_channel_group` of a channel that they never\nsubscribed to, but not an organization administrator, the channel\nin question would not be part of this array.\n" - }, - "channel_folders": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChannelFolder" - }, - "description": "Present if `channel_folders` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary describes one\nof the channel folders in the organization.\n\nOnly channel folders with one or more public web channels are\nvisible to spectators.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" - }, - "unread_msgs": { - "type": "object", - "description": "Present if `message` and `update_message_flags` are both present in\n`event_types`.\n\nA set of data structures describing the conversations containing\nthe 50000 most recent unread messages the user has received. This will usually\ncontain every unread message the user has received, but clients should support\nusers with even more unread messages (and not hardcode the number 50000).\n", - "additionalProperties": false, - "properties": { - "count": { - "type": "integer", - "description": "The total number of unread messages to display. This includes one-on-one and group\ndirect messages, as well as channel messages that are not [muted](/help/mute-a-topic).\n\n**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow\ntopic features were not handled correctly in calculating this field.\n" - }, - "pms": { - "type": "array", - "description": "An array of objects where each object contains details of unread\none-on-one direct messages with a specific user.\n\nNote that it is possible for a message that the current user sent\nto the specified user to be marked as unread and thus appear here.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "other_user_id": { - "type": "integer", - "description": "The user ID of the other participant in this one-on-one direct\nmessage conversation. Will be the current user's ID for messages\nthat they sent in a one-on-one direct message conversation with\nthemself.\n\n**Changes**: New in Zulip 5.0 (feature level 119), replacing\nthe less clearly named `sender_id` field.\n" - }, - "sender_id": { - "deprecated": true, - "type": "integer", - "description": "Old name for the `other_user_id` field. Clients should access\nthis field in Zulip server versions that do not yet support\n`other_user_id`.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 119).\nWe expect to provide a next version of the full `unread_msgs`\nAPI before removing this legacy name.\n" - }, - "unread_message_ids": { - "type": "array", - "description": "The message IDs of the recent unread direct messages sent\nby either user in this one-on-one direct message conversation,\nsorted in ascending order.\n", - "items": { - "type": "integer" - } - } - } - } - }, - "streams": { - "type": "array", - "description": "An array of dictionaries where each dictionary contains details of all\nunread messages of a single subscribed channel. This includes muted channels\nand muted topics, even though those messages are excluded from `count`.\n\n**Changes**: Prior to Zulip 5.0 (feature level 90), these objects\nincluded a `sender_ids` property, which listed the set of IDs of\nusers who had sent the unread messages.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "topic": { - "type": "string", - "description": "The topic under which the messages were sent.\n\nNote that the empty string topic may have been rewritten by the server\nto the value of `realm_empty_topic_display_name` found in the\n[`POST /register`](/api/register-queue) response depending on the value\nof the `empty_topic_name` [client capability][client-capabilities].\n\n**Changes**: The `empty_topic_name` client capability is new in\nZulip 10.0 (feature level 334).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "stream_id": { - "type": "integer", - "description": "The ID of the channel to which the messages were sent.\n" - }, - "unread_message_ids": { - "type": "array", - "description": "The message IDs of the recent unread messages sent in this channel,\nsorted in ascending order.\n", - "items": { - "type": "integer" - } - } - } - } - }, - "huddles": { - "type": "array", - "description": "An array of objects where each object contains details of unread\ngroup direct messages with a specific group of users.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "user_ids_string": { - "type": "string", - "description": "A string containing the IDs of all users in the group\ndirect message conversation, including the current user,\nseparated by commas and sorted numerically; for example:\n`\"1,2,3\"`.\n" - }, - "unread_message_ids": { - "type": "array", - "description": "The message IDs of the recent unread messages which have been sent in\nthis group direct message conversation, sorted in ascending order.\n", - "items": { - "type": "integer" - } - } - } - } - }, - "mentions": { - "type": "array", - "description": "Array containing the IDs of all unread messages in which the user was\nmentioned directly, and unread [non-muted](/help/mute-a-topic) messages\nin which the user was mentioned through a wildcard.\n\n**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow\ntopic features were not handled correctly in calculating this field.\n", - "items": { - "type": "integer" - } - }, - "old_unreads_missing": { - "type": "boolean", - "description": "Whether this data set was truncated because the user has too many\nunread messages. When truncation occurs, only the most recent\n`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered\nwhen forming this response. When `true`, we recommend that clients\ndisplay a warning, as they are likely to produce erroneous results\nuntil reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`\nunread messages.\n\n**Changes**: New in Zulip 4.0 (feature level 44).\n" - } - } - }, - "starred_messages": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Present if `starred_messages` is present in `fetch_event_types`.\n\nArray containing the IDs of all messages which have been\n[starred](/help/star-a-message) by the user.\n" - }, - "streams": { - "type": "array", - "items": { - "$ref": "#/components/schemas/BasicChannel" - }, - "description": "Present if `stream` is present in `fetch_event_types`.\n\nArray of dictionaries where each dictionary contains details about\na single channel in the organization that is visible to the user.\n\nFor organization administrators, this will include all private channels\nin the organization.\n\n**Changes**: Before Zulip 11.0 (feature level 378), archived channels\ndid not appear in this list, even if the `archived_channels` [client\ncapability][client-capabilities] was declared by the client.\n\nAs of Zulip 8.0 (feature level 205), this will include all web-public\nchannels in the organization as well.\n" - }, - "realm_default_streams": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Present if `default_streams` is present in `fetch_event_types`.\n\nAn array of IDs of all the [default channels](/help/set-default-streams-for-new-users)\nin the organization.\n\n**Changes**: Before Zulip 10.0 (feature level 330), we sent\narray of dictionaries where each dictionary contained details\nabout a single default stream for the Zulip organization.\n" - }, - "realm_default_stream_groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DefaultChannelGroup" - }, - "description": "Present if `default_stream_groups` is present in `fetch_event_types`.\n\nAn array of dictionaries where each dictionary contains details\nabout a single default channel group configured for this\nZulip organization.\n\nDefault channel groups are an experimental feature.\n" - }, - "stop_words": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Present if `stop_words` is present in `fetch_event_types`.\n\nAn array containing the stop words used by the Zulip server's\nfull-text search implementation. Useful for showing helpful\nerror messages when a search returns limited results because\na stop word in the query was ignored.\n" - }, - "user_status": { - "type": "object", - "description": "Present if `user_status` is present in `fetch_event_types`.\n\nA dictionary which contains the [status](/help/status-and-availability)\nof all users in the Zulip organization who have set a status.\n\n**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).\nPreviously, Zulip did not support emoji associated with statuses.\n", - "additionalProperties": { - "allOf": [ - { - "description": "`{user_id}`: Object containing the status details of a user\nwith the key of the object being the ID of the user.\n" - }, - { - "$ref": "#/components/schemas/UserStatus" - } - ] - } - }, - "user_settings": { - "type": "object", - "description": "Present if `user_settings` is present in `fetch_event_types`.\n\nA dictionary containing the user's personal settings.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0\n(feature level 364) as we now have `web_font_size_px` and\n`web_line_height_percent` settings for more control.\n\nNew in Zulip 5.0 (feature level 89). Previously, these\nsettings appeared in the top-level object, where they are\navailable for clients without the `user_settings_object` client\ncapability for backwards-compatibility.\n", - "additionalProperties": false, - "properties": { - "twenty_four_hour_time": { - "type": "boolean", - "nullable": true, - "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\nA `null` value indicates that the client should use the default time\nformat for the user's locale.\n\n**Changes**: Prior to Zulip 11.0 (feature level 408), `null`\nwas not a valid value for this setting. Note that it was not possible\nto actually set the time format to `null` at this feature level.\n" - }, - "web_mark_read_on_scroll_policy": { - "type": "integer", - "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n" - }, - "web_channel_default_view": { - "type": "integer", - "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n" - }, - "starred_message_counts": { - "type": "boolean", - "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n" - }, - "receives_typing_notifications": { - "type": "boolean", - "description": "Whether the user is configured to receive typing notifications from\nother users. The server will only deliver typing notifications events\nto users who for whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" - }, - "web_suggest_update_timezone": { - "type": "boolean", - "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n" - }, - "fluid_layout_width": { - "type": "boolean", - "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n" - }, - "high_contrast_mode": { - "type": "boolean", - "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n" - }, - "web_font_size_px": { - "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", - "type": "integer", - "example": 14 - }, - "web_line_height_percent": { - "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", - "type": "integer", - "example": 122 - }, - "color_scheme": { - "type": "integer", - "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n" - }, - "translate_emoticons": { - "type": "boolean", - "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n" - }, - "display_emoji_reaction_users": { - "type": "boolean", - "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting\nusers, rather than a count, for messages with few total\nreactions. The ideal cutoff may depend on the space\navailable for displaying reactions; the official web\napplication displays names when 3 or fewer total reactions\nare present with this setting enabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n" - }, - "default_language": { - "type": "string", - "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n" - }, - "web_home_view": { - "type": "string", - "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n" - }, - "web_escape_navigates_to_home_view": { - "type": "boolean", - "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n" - }, - "left_side_userlist": { - "type": "boolean", - "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n" - }, - "emojiset": { - "type": "string", - "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n" - }, - "demote_inactive_streams": { - "type": "integer", - "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n" - }, - "user_list_style": { - "type": "integer", - "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n" - }, - "web_animate_image_previews": { - "type": "string", - "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n" - }, - "web_stream_unreads_count_display_policy": { - "type": "integer", - "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n" - }, - "hide_ai_features": { - "type": "boolean", - "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - }, - "web_left_sidebar_show_channel_folders": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n" - }, - "web_left_sidebar_unreads_count_summary": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n" - }, - "timezone": { - "type": "string", - "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n" - }, - "enter_sends": { - "type": "boolean", - "description": "Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)\nin the compose box is enabled.\n" - }, - "enable_drafts_synchronization": { - "type": "boolean", - "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n" - }, - "enable_stream_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for channel messages.\n" - }, - "enable_stream_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for channel messages.\n" - }, - "enable_stream_push_notifications": { - "type": "boolean", - "description": "Enable mobile notifications for channel messages.\n" - }, - "enable_stream_audible_notifications": { - "type": "boolean", - "description": "Enable audible desktop notifications for channel messages.\n" - }, - "notification_sound": { - "type": "string", - "description": "Notification sound name.\n" - }, - "enable_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for direct messages and @-mentions.\n" - }, - "enable_sounds": { - "type": "boolean", - "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n" - }, - "enable_followed_topic_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_push_notifications": { - "type": "boolean", - "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_audible_notifications": { - "type": "boolean", - "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "email_notifications_batching_period_seconds": { - "type": "integer", - "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n" - }, - "enable_offline_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n" - }, - "enable_offline_push_notifications": { - "type": "boolean", - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n" - }, - "enable_online_push_notifications": { - "type": "boolean", - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n" - }, - "enable_digest_emails": { - "type": "boolean", - "description": "Enable digest emails when the user is away.\n" - }, - "enable_marketing_emails": { - "type": "boolean", - "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n" - }, - "enable_login_emails": { - "type": "boolean", - "description": "Enable email notifications for new logins to account.\n" - }, - "message_content_in_email_notifications": { - "type": "boolean", - "description": "Include the message's content in email notifications for new messages.\n" - }, - "pm_content_in_desktop_notifications": { - "type": "boolean", - "description": "Include content of direct messages in desktop notifications.\n" - }, - "wildcard_mentions_notify": { - "type": "boolean", - "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n" - }, - "enable_followed_topic_wildcard_mentions_notify": { - "type": "boolean", - "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "desktop_icon_count_display": { - "type": "integer", - "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,\nand followed topics` option, renumbering the options to insert it in\norder.\n" - }, - "realm_name_in_email_notifications_policy": { - "type": "integer", - "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n" - }, - "automatically_follow_topics_policy": { - "type": "integer", - "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "type": "integer", - "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" - }, - "automatically_follow_topics_where_mentioned": { - "type": "boolean", - "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n" - }, - "resolved_topic_notice_auto_read_policy": { - "type": "string", - "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n" - }, - "presence_enabled": { - "type": "boolean", - "description": "Display the presence status to other users when online.\n" - }, - "available_notification_sounds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Array containing the names of the notification sound options\nsupported by this Zulip server. Only relevant to support UI\nfor configuring notification sounds.\n" - }, - "emojiset_choices": { - "description": "Array of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n", - "type": "array", - "items": { - "type": "object", - "description": "Object describing a emoji set.\n", - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" - }, - "text": { - "type": "string", - "description": "The text describing the emoji set.\n" - } - } - } - }, - "send_private_typing_notifications": { - "type": "boolean", - "description": "Whether the user has chosen to send [typing\nnotifications](/help/typing-notifications)\nwhen composing direct messages. The client should send typing\nnotifications for direct messages if and only if this setting is enabled.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "send_stream_typing_notifications": { - "type": "boolean", - "description": "Whether the user has chosen to send [typing\nnotifications](/help/typing-notifications)\nwhen composing channel messages. The client should send typing\nnotifications for channel messages if and only if this setting is enabled.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "send_read_receipts": { - "type": "boolean", - "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "allow_private_data_export": { - "type": "boolean", - "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n" - }, - "email_address_visibility": { - "$ref": "#/components/schemas/EmailAddressVisibility" - }, - "web_navigate_to_sent_message": { - "type": "boolean", - "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n" - } - } - }, - "user_topics": { - "type": "array", - "description": "Present if `user_topic` is present in `fetch_event_types`.\n\n**Changes**: New in Zulip 6.0 (feature level 134), deprecating and\nreplacing the previous `muted_topics` structure.\n", - "items": { - "type": "object", - "description": "Object describing the user's configuration for a given topic.\n", - "additionalProperties": false, - "properties": { - "stream_id": { - "type": "integer", - "description": "The ID of the channel to which the topic belongs.\n" - }, - "topic_name": { - "type": "string", - "description": "The name of the topic.\n\nNote that the empty string topic may have been rewritten by the server to\nthe value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue)\nresponse depending on the value of the `empty_topic_name` [client capability][client-capabilities].\n\n**Changes**: The `empty_topic_name` client capability is new in\nZulip 10.0 (feature level 334).\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "last_updated": { - "type": "integer", - "description": "An integer UNIX timestamp representing when the user-topic\nrelationship was changed.\n" - }, - "visibility_policy": { - "type": "integer", - "description": "An integer indicating the user's visibility configuration for\nthe topic.\n\n- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).\n- 2 = Unmuted. Used to record [unmuted topics](/help/mute-a-topic).\n- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n\nIn Zulip 7.0 (feature level 170), added unmuted as a visibility\npolicy option.\n" - } - } - } - }, - "has_zoom_token": { - "type": "boolean", - "description": "Present if `video_calls` is present in `fetch_event_types`.\n\nA boolean which signifies whether the user has a Zoom token and has thus\ncompleted OAuth flow for the [Zoom integration](/help/configure-call-provider).\nClients need to know whether initiating Zoom OAuth is required before\ncreating a Zoom call.\n" - }, - "giphy_api_key": { - "type": "string", - "description": "Present if `giphy` is present in `fetch_event_types`.\n\nGIPHY's client-side SDKs needs this API key to use the GIPHY API.\nGIPHY API keys are not secret (their main purpose appears to be\nallowing GIPHY to block a problematic app). Please don't use our API\nkey for an app unrelated to Zulip.\n\nDevelopers of clients should also read the\n[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)\nbefore using this API key.\n\n**Changes**: Added in Zulip 4.0 (feature level 47).\n" - }, - "push_devices": { - "type": "object", - "description": "Present if `push_device` is present in `fetch_event_types`.\n\nDictionary where each entry describes the user's push device's\nregistration status and error code (if registration failed).\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n", - "additionalProperties": { - "description": "`{push_account_id}`: Dictionary containing the details of\na push device with the push account ID as the key.\n", - "type": "object", - "additionalProperties": false, - "properties": { - "status": { - "type": "string", - "description": "The push account's registration status.\nEither `\"active\"`, `\"pending\"`, or `\"failed\"`.\n" - }, - "error_code": { - "type": "string", - "nullable": true, - "description": "If the status is `\"failed\"`, a [Zulip API error\ncode](/api/rest-error-handling) indicating the type of failure that\noccurred.\n\nThe following error codes have recommended client behavior:\n\n- `\"INVALID_BOUNCER_PUBLIC_KEY\"` - Inform the user to update app.\n- `\"REQUEST_EXPIRED` - Retry with a fresh payload.\n" - } - } - } - }, - "enable_desktop_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_digest_emails": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_login_emails": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_marketing_emails": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "email_notifications_batching_period_seconds": { - "deprecated": true, - "type": "integer", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_offline_email_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_offline_push_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_online_push_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_sounds": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_stream_desktop_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_stream_email_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_stream_push_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_stream_audible_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "wildcard_mentions_notify": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "message_content_in_email_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "notification_sound": { - "deprecated": true, - "type": "string", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "pm_content_in_desktop_notifications": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "desktop_icon_count_display": { - "deprecated": true, - "type": "integer", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "realm_name_in_email_notifications_policy": { - "deprecated": true, - "type": "integer", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: In Zulip 7.0 (feature level 168), replaced previous\n`realm_name_in_notifications` global notifications setting with\n`realm_name_in_email_notifications_policy`.\n\n**Deprecated** since Zulip 5.0 (feature level 89); both\n`realm_name_in_notifications` and the newer\n`realm_name_in_email_notifications_policy` are deprecated. Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "presence_enabled": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nThe current value of this global notification setting for the user.\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "available_notification_sounds": { - "deprecated": true, - "type": "array", - "items": { - "type": "string" - }, - "description": "Present if `update_global_notifications` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in their\n[`client_capabilities`][capabilities] when registering the event queue.\n\nArray containing the names of the notification sound options supported by\nthis Zulip server. Only relevant to support UI for configuring notification\nsounds.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "color_scheme": { - "deprecated": true, - "type": "integer", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe color scheme selected by the user.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "default_language": { - "deprecated": true, - "type": "string", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe default language chosen by the user.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "demote_inactive_streams": { - "deprecated": true, - "type": "integer", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen to hide inactive channels.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "emojiset": { - "deprecated": true, - "type": "string", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe name of the emoji set that the user has chosen.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "enable_drafts_synchronization": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether drafts synchronization is enabled for the user. If disabled,\nclients will receive an error when trying to use the `drafts` endpoints.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\nNew in Zulip 5.0 (feature level 87).\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "fluid_layout_width": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for the layout width to be fluid.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "web_home_view": { - "deprecated": true, - "type": "string", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe [home view](/help/configure-home-view) in Zulip, represented\nas the URL suffix after `#` to be rendered when Zulip loads.\n\nCurrently supported values are `all_messages` and `recent_topics`.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n\n**Deprecated** in Zulip 5.0 (feature level 89). Clients connecting to newer\nservers should declare the `user_settings_object` client capability and\naccess the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "high_contrast_mode": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether has switched on high contrast mode.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "left_side_userlist": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for the userlist to be displayed\non the left side of the screen (for desktop app and web app) in narrow\nwindows.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "starred_message_counts": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen the number of starred messages to\nbe displayed similar to unread counts.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "timezone": { - "deprecated": true, - "type": "string", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nThe user's [profile time zone](/help/change-your-timezone), which is\nused primarily to display the user's local time to other users.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "translate_emoticons": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen for emoticons to be translated into emoji\nin the Zulip compose box.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "twenty_four_hour_time": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user has chosen a twenty four hour time display (true)\nor a twelve hour one (false).\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "receives_typing_notifications": { - "type": "boolean", - "description": "Whether the user is configured to receive typing notifications from other\nusers. The server will only deliver typing notifications events to users who\nfor whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" - }, - "enter_sends": { - "deprecated": true, - "type": "boolean", - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nWhether the user setting for [sending on pressing Enter][set-enter-send]\nin the compose box is enabled.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and process the `user_settings` event type instead.\n\nPrior to Zulip 5.0 (feature level 84), this field was present\nin response if `realm_user` was present in `fetch_event_types`, not\n`update_display_settings`.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n[set-enter-send]: /help/configure-send-message-keys\n" - }, - "emojiset_choices": { - "deprecated": true, - "description": "Present if `update_display_settings` is present in `fetch_event_types`\nand only for clients that did not include `user_settings_object` in\ntheir [`client_capabilities`][capabilities] when registering the event queue.\n\nArray of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients\nconnecting to newer servers should declare the `user_settings_object`\nclient capability and access the `user_settings` object instead.\n\n[capabilities]: /api/register-queue#parameter-client_capabilities\n", - "type": "array", - "items": { - "type": "object", - "description": "Object describing a emoji set.\n", - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" - }, - "text": { - "type": "string", - "description": "The text describing the emoji set.\n" - } - } - } - }, - "realm_message_edit_history_visibility_policy": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhat typesof message edit history are accessible to users via\n[message edit history](/help/view-a-messages-edit-history).\n\n- \"all\" = All edit history is visible.\n- \"moves\" = Only moves are visible.\n- \"none\" = No edit history is visible.\n\n**Changes**: New in Zulip 10.0 (feature level 358), replacing the previous\n`allow_edit_history` boolean setting; `true` corresponds to `all`,\nand `false` to `none`.\n" - }, - "realm_allow_edit_history": { - "deprecated": true, - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization is configured to allow users to access\n[message edit history](/help/view-a-messages-edit-history).\n\nThe value of `realm_allow_edit_history` is set as `false` if the\n`realm_message_edit_history_visibility_policy` is configured as \"None\"\nand `true` if it is configured as \"Moves only\" or \"All\".\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 358) and will be\nremoved in the future, as it is an inaccurate version\n`realm_message_edit_history_visibility_policy`, which replaces this field.\n" - }, - "realm_can_add_custom_emoji_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add custom emoji in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 307). Previously, this\npermission was controlled by the enum `add_custom_emoji_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n\nBefore Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`\nboolean setting controlled this permission; `true` corresponded to `Admins`,\nand `false` to `Everyone`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_add_subscribers_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to add subscribers to channels in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 341). Previously, this\npermission was controlled by the enum `invite_to_stream_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_delete_any_message_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete any message in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 281). Previously, this\npermission was limited to administrators only and was uneditable.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_delete_own_message_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to delete messages that they have sent in the\norganization.\n\n**Changes**: New in Zulip 10.0 (feature level 291). Previously, this\npermission was controlled by the enum `delete_own_message_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.\n\nBefore Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean\nsetting controlled this permission; `true` corresponded to `Everyone`, and\n`false` to `Admins`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_set_delete_message_policy_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `can_delete_any_message_group`\nand `can_delete_own_message_group` permission settings. Note that the user\nmust be a member of both this group and the `can_administer_channel_group`\nof the channel whose message delete settings they want to change.\n\nOrganization administrators can always change these settings of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_set_topics_policy_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to change per-channel `topics_policy` setting. Note that\nthe user must be a member of both this group and the `can_administer_channel_group`\nof the channel whose `topics_policy` they want to change.\n\nOrganization administrators can always change the `topics_policy` setting of\nevery channel.\n\n**Changes**: New in Zulip 11.0 (feature level 392).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_invite_users_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to send email invitations for inviting other users\nto the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 321). Previously, this\npermission was controlled by the enum `invite_to_realm_policy`. Values\nwere 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nBefore Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean\nsetting controlled this permission; `true` corresponded to `Admins`, and\n`false` to `Members`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_mention_many_users_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using mentions in large\nchannels, even when permitted to do so.\n\n**Changes**: New in Zulip 10.0 (feature level 352). Previously, this\npermission was controlled by the enum `wildcard_mention_policy`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_move_messages_between_channels_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one channel to another\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 310). Previously, this\npermission was controlled by the enum `move_messages_between_streams_policy`.\nValues were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`move_messages_between_streams_policy` enum.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_move_messages_between_topics_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to move messages from one topic to another\nwithin a channel in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 316). Previously, this\npermission was controlled by the enum `edit_topic_policy`. Values were\n1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.\n\nIn Zulip 7.0 (feature level 159), `Nobody` was added as an option to\n`edit_topic_policy` enum.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_can_create_groups": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create user\ngroups in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 299). Previously\n`realm_user_group_edit_policy` field used to control the\npermission to create user groups.\n" - } - ] - }, - "realm_can_create_bots_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create all types of bot users\nin the organization. See also `can_create_write_only_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" - } - ] - }, - "realm_can_create_write_only_bots_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create bot users that\ncan only send messages in the organization, i.e. incoming webhooks,\nin addition to the users who are present in `can_create_bots_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 344). Previously, this\npermission was controlled by the enum `bot_creation_policy`. Values\nwere 1=Members, 2=Generic bots limited to administrators, 3=Administrators.\n" - } - ] - }, - "realm_can_manage_all_groups": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - } - ] - }, - "realm_can_manage_billing_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to manage plans and billing in the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners\nand users with `is_billing_admin` property set to `true` were allowed to\nmanage plans and billing.\n" - } - ] - }, - "realm_can_create_public_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create public\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 264). Previously\n`realm_create_public_stream_policy` field used to control the\npermission to create public channels.\n" - } - ] - }, - "realm_can_create_private_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create private\nchannels in this organization.\n\n**Changes**: New in Zulip 9.0 (feature level 266). Previously\n`realm_create_private_stream_policy` field used to control the\npermission to create private channels.\n" - } - ] - }, - "realm_can_create_web_public_channel_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to create web-public\nchannels in this organization.\n\nHas no effect and should not be displayed in settings UI\nunless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`\nserver-level setting enabled and the organization has enabled\nthe `enable_spectator_access` realm setting.\n\n**Changes**: New in Zulip 10.0 (feature level 280). Previously\n`realm_create_web_public_stream_policy` field used to control\nthe permission to create web-public channels.\n" - } - ] - }, - "realm_can_resolve_topics_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining\nthe set of users who have permission to [resolve topics](/help/resolve-a-topic)\nin the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 367). Previously, permission\nto resolve topics was controlled by the more general\n`can_move_messages_between_topics_group permission for moving messages`.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_create_public_stream_policy": { - "type": "integer", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create public channels in the organization,\navailable for backwards-compatibility. Clients should use\n`can_create_public_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Members only\n- 2 = Admins only\n- 3 = [Full members][calc-full-member] only\n- 4 = Admins and moderators only\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 264) and\nreplaced by `realm_can_create_public_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\nBefore Zulip 5.0 (feature level 102), permission to create\nchannels was controlled by the `realm_create_stream_policy` setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "realm_create_private_stream_policy": { - "type": "integer", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create private channels in the organization,\navailable for backwards-compatibility. Clients should use\n`can_create_private_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Members only\n- 2 = Admins only\n- 3 = [Full members][calc-full-member] only\n- 4 = Admins and moderators only\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 266) and\nreplaced by `realm_can_create_private_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\n**Changes**: Before Zulip 5.0 (feature level 102), permission to\ncreate channels was controlled by the `realm_create_stream_policy` setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "realm_create_web_public_stream_policy": { - "type": "integer", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to create web-public channels in the\norganization, available for backwards-compatibility. Clients\nshould use `can_create_web_public_channel_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 2 = Admins only\n- 4 = Admins and moderators only\n- 6 = Nobody\n- 7 = Owners only\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 280) and\nreplaced by `realm_can_create_web_public_channel_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\n**Changes**: Added in Zulip 5.0 (feature level 103).\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n" - }, - "realm_wildcard_mention_policy": { - "type": "integer", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA deprecated representation of a superset of the users who\nhave permission to use wildcard mentions in large channels,\navailable for backwards-compatibility. Clients should use\n`can_mention_many_users_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can use wildcard mentions in large channels.\n- 2 = Only members can use wildcard mentions in large channels.\n- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.\n- 5 = Only organization administrators can use wildcard mentions in large channels.\n- 6 = Nobody can use wildcard mentions in large channels.\n- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.\n\nAll users will receive a warning/reminder when using\nmentions in large channels, even when permitted to do so.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 352) and\nreplaced by `realm_can_mention_many_users_group`, which\nsupports finer resolution of configurations, resulting in this\nproperty being inaccurate following that transition.\n\nChannel administrators option removed in Zulip 6.0 (feature level 133).\n\nModerators option added in Zulip 4.0 (feature level 62).\n\nNew in Zulip 4.0 (feature level 33).\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "realm_default_language": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe [organization language][org-lang] for automated messages and invitation emails.\n\n[org-lang]: /help/configure-organization-language\n" - }, - "realm_welcome_message_custom_text": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis organization's configured custom message for Welcome Bot\nto send to new user accounts, in Zulip Markdown format.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n" - }, - "realm_description": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe description of the organization, used on login and registration pages.\n" - }, - "realm_digest_emails_enabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has enabled [weekly digest emails](/help/digest-emails).\n" - }, - "realm_disallow_disposable_email_addresses": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization disallows disposable email\naddresses.\n" - }, - "realm_email_changes_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether users are allowed to change their own email address in this\norganization. This is typically disabled for organizations that\nsynchronize accounts from LDAP or a similar corporate database.\n" - }, - "realm_invite_required": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether an invitation is required to join this organization.\n" - }, - "realm_create_multiuse_invite_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to create [reusable invitation\nlinks](/help/invite-new-users#create-a-reusable-invitation-link)\nto the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 209).\n" - } - ] - }, - "realm_inline_image_preview": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization has been configured to enable\n[previews of linked images](/help/image-video-and-website-previews).\n" - }, - "realm_inline_url_embed_preview": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization has been configured to enable\n[previews of linked websites](/help/image-video-and-website-previews).\n" - }, - "realm_topics_policy": { - "type": "string", - "enum": ["allow_empty_topic", "disable_empty_topic"], - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe organization's default policy for sending channel messages to the\n[empty \"general chat\" topic](/help/require-topics).\n\n- `\"allow_empty_topic\"`: Channel messages can be sent to the empty topic.\n- `\"disable_empty_topic\"`: Channel messages cannot be sent to the empty topic.\n\n**Changes**: New in Zulip 11.0 (feature level 392). Previously, this was\ncontrolled by the boolean `realm_mandatory_topics` setting, which is now\ndeprecated.\n" - }, - "realm_mandatory_topics": { - "type": "boolean", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether [topics are required](/help/require-topics) for messages in this\norganization.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now\ncontrolled by the realm `topics_policy` setting.\n" - }, - "realm_message_retention_days": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe default [message retention policy](/help/message-retention-policy)\nfor this organization. It can have one special value:\n\n- `-1` denoting that the messages will be retained forever for this realm, by default.\n\n**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was\nencoded as `null` instead of `-1`. Clients can correctly handle all\nserver versions by treating both `-1` and `null` as indicating\nunlimited message retention.\n" - }, - "realm_name": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe name of the organization, used in login pages etc.\n" - }, - "realm_require_e2ee_push_notifications": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this realm is configured to disallow sending mobile\npush notifications with message content through the legacy\nmobile push notifications APIs. The new API uses end-to-end\nencryption to protect message content and metadata from\nbeing accessible to the push bouncer service, APNs, and\nFCM. Clients that support the new E2EE API will use it\nautomatically regardless of this setting.\n\nIf `true`, mobile push notifications sent to clients that\nlack support for E2EE push notifications will always have\n\"New message\" as their content. Note that these legacy\nmobile notifications will still contain metadata, which may\ninclude the message's ID, the sender's name, email address,\nand avatar.\n\nIn a future release, once the official mobile apps have\nimplemented fully validated their E2EE protocol support,\nthis setting will become strict, and disable the legacy\nprotocol entirely.\n\n**Changes**: New in Zulip 11.0 (feature level 409). Previously,\nthis behavior was available only via the\n`PUSH_NOTIFICATION_REDACT_CONTENT` global server setting.\n" - }, - "realm_require_unique_names": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether the organization is configured to require users\nto have unique full names. If true, the server will reject attempts\nto create a new user, or change the name of an existing user, where\ndoing so would lead to two users whose names are identical modulo\ncase and unicode normalization.\n\n**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip\nserver could not be configured to enforce unique names.\n" - }, - "realm_name_changes_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their name\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" - }, - "realm_avatar_changes_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nIndicates whether users are\n[allowed to change](/help/restrict-name-and-email-changes) their avatar\nvia the Zulip UI in this organization. Typically disabled\nin organizations syncing this type of account information from\nan external user database like LDAP.\n" - }, - "realm_emails_restricted_to_domains": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)\nthis organization are required to have an email\naddress in one of the `realm_domains` configured for the organization.\n" - }, - "realm_send_welcome_emails": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether or not this organization is configured to send the standard Zulip\n[welcome emails](/help/disable-welcome-emails) to new users joining the organization.\n" - }, - "realm_message_content_allowed_in_email_notifications": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether notification emails in this organization are allowed to\ncontain Zulip the message content, or simply indicate that a new\nmessage was sent.\n" - }, - "realm_enable_spectator_access": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether web-public channels and related anonymous access APIs/features\nare enabled in this organization.\n\nCan only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`\n[server setting][server-settings] is enabled on the Zulip\nserver. See also the `can_create_web_public_channel_group` realm\nsetting.\n\n**Changes**: New in Zulip 5.0 (feature level 109).\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n" - }, - "realm_want_advertise_in_communities_directory": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has given permission to be advertised in the\nZulip [communities directory](/help/communities-directory).\n\nUseful only to clients supporting changing this setting for the\norganization.\n\nGiving permission via this setting does not guarantee that an\norganization will be listed in the Zulip communities directory.\n\n**Changes**: New in Zulip 6.0 (feature level 129).\n" - }, - "realm_video_chat_provider": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe configured [video call provider](/help/configure-call-provider) for the\norganization.\n\n- 0 = None\n- 1 = Jitsi Meet\n- 3 = Zoom (User OAuth integration)\n- 4 = BigBlueButton\n- 5 = Zoom (Server to Server OAuth integration)\n\nNote that only one of the [Zoom integrations][zoom-video-calls] can\nbe configured on a Zulip server.\n\n**Changes**: In Zulip 10.0 (feature level 353), added the Zoom Server\nto Server OAuth option.\n\nIn Zulip 3.0 (feature level 1), added the None option\nto disable video call UI.\n\n[zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom\n" - }, - "realm_jitsi_server_url": { - "type": "string", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the custom Jitsi Meet server configured in this organization's\nsettings.\n\n`null`, the default, means that the organization is using the should use the\nserver-level configuration, `server_jitsi_server_url`. A correct client\nsupporting only the modern API should use `realm_jitsi_server_url ||\nserver_jitsi_server_url` to create calls.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only\navailable as a server-level configuration, which was available via the\n`jitsi_server_url` field.\n" - }, - "realm_giphy_rating": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe configured GIPHY rating for the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 55).\n" - }, - "realm_waiting_period_threshold": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMembers whose accounts have been created at least this many days ago\nwill be treated as [full members][calc-full-member]\nfor the purpose of settings that restrict access to new members.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "realm_digest_weekday": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe day of the week when the organization will send\nits weekly digest email to inactive users.\n" - }, - "realm_direct_message_initiator_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to start a new direct message conversation\ninvolving other non-bot users. Users who are outside this group and attempt\nto send the first direct message to a given collection of recipient users\nwill receive an error, unless all other recipients are bots or the sender.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_direct_message_permission_group": { - "allOf": [ - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the set of\nusers who have permission to fully use direct messages. Users outside\nthis group can only send direct messages to conversations where all the\nrecipients are in this group, are bots, or are the sender, ensuring that\nevery direct message conversation will be visible to at least one user in\nthis group.\n\n**Changes**: New in Zulip 9.0 (feature level 270).\n\nPreviously, access to send direct messages was controlled by the\n`private_message_policy` realm setting, which supported values of\n1 (enabled) and 2 (disabled).\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "realm_default_code_block_language": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe default pygments language code to be used for code blocks in this\norganization. If an empty string, no default has been set.\n\n**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant\nthat both `null` and an empty string could represent that no default was\nset for this realm setting. Clients supporting older server versions\nshould treat either value (`null` or `\"\"`) as no default being set.\n" - }, - "realm_message_content_delete_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be deleted\nwith this organization's\n[message deletion policy](/help/restrict-message-editing-and-deletion).\n\nWill not be 0. A `null` value means no limit: messages can be deleted\nregardless of how long ago they were sent.\n\n**Changes**: No limit was represented using the\nspecial value `0` before Zulip 5.0 (feature level 100).\n" - }, - "realm_authentication_methods": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/RealmAuthenticationMethod" - }, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary of authentication method keys mapped to dictionaries that\ndescribe the properties of the named authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n\nClients should use this to implement server-settings UI to change which\nmethods are enabled for the organization. For authentication UI itself,\nclients should use the pre-authentication metadata returned by\n[`GET /server_settings`](/api/get-server-settings).\n\n**Changes**: In Zulip 9.0 (feature level 241), the values in this\ndictionary were changed. Previously, the values were a simple boolean\nindicating whether the backend is enabled or not.\n" - }, - "realm_allow_message_editing": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this organization's [message edit policy][config-message-editing]\nallows editing the content of messages.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n[config-message-editing]: /help/restrict-message-editing-and-deletion\n" - }, - "realm_message_content_edit_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be edited\nwith this organization's\n[message edit policy](/help/restrict-message-editing-and-deletion).\n\nWill not be `0`. A `null` value means no limit, so messages can be edited\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: Before Zulip 6.0 (feature level 138), no limit was\nrepresented using the special value `0`.\n" - }, - "realm_move_messages_within_stream_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be moved within a\nchannel to another topic by users who have permission to do so based on this\norganization's [topic edit policy](/help/restrict-moving-messages). This\nsetting does not affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so message topics can be\nedited regardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time\nlimit was always 72 hours for users who were not administrators or\nmoderators.\n" - }, - "realm_move_messages_between_streams_limit_seconds": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMessages sent more than this many seconds ago cannot be moved between\nchannels by users who have permission to do so based on this organization's\n[message move policy](/help/restrict-moving-messages). This setting does\nnot affect moderators and administrators.\n\nWill not be `0`. A `null` value means no limit, so messages can be moved\nregardless of how long ago they were sent.\n\nSee [`PATCH /messages/{message_id}`](/api/update-message) for details and\nhistory of how message editing permissions work.\n\n**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was\nno time limit for moving messages between channels for users with permission\nto do so.\n" - }, - "realm_enable_read_receipts": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether read receipts is enabled in the organization or not.\n\nIf disabled, read receipt data will be unavailable to clients, regardless\nof individual users' personal read receipt settings. See also the\n`send_read_receipts` setting within `realm_user_settings_defaults`.\n\n**Changes**: New in Zulip 6.0 (feature level 137).\n" - }, - "realm_icon_url": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's [profile icon](/help/create-your-organization-profile).\n" - }, - "realm_icon_source": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's\n[profile icon](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the organization's icon.\n\n- \"G\" means generated by Gravatar (the default).\n- \"U\" means uploaded by an organization administrator.\n" - }, - "max_icon_file_size_mib": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size allowed for the organization's\nicon. Useful for UI allowing editing the organization's icon.\n\n**Changes**: New in Zulip 5.0 (feature level 72). Previously,\nthis was called `max_icon_file_size`.\n" - }, - "realm_logo_url": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's wide logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" - }, - "realm_logo_source": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" - }, - "realm_night_logo_url": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the organization's dark theme wide-format logo configured in the\n[organization profile](/help/create-your-organization-profile).\n" - }, - "realm_night_logo_source": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nString indicating whether the organization's dark theme\n[profile wide logo](/help/create-your-organization-profile) was uploaded\nby a user or is the default. Useful for UI allowing editing the\norganization's wide logo.\n\n- \"D\" means the logo is the default Zulip logo.\n- \"U\" means uploaded by an organization administrator.\n" - }, - "max_logo_file_size_mib": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size allowed for the uploaded organization logos.\n\n**Changes**: New in Zulip 5.0 (feature level 72). Previously,\nthis was called `max_logo_file_size`.\n" - }, - "realm_bot_domain": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe fake email domain that will be used for new bots created this\norganization. Useful for UI for creating bots.\n" - }, - "realm_uri": { - "type": "string", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL for the organization. Alias of `realm_url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" - }, - "realm_url": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL for the organization.\n\n**Changes**: New in Zulip 9.0 (feature level 257), replacing the\ndeprecated `realm_uri`.\n" - }, - "realm_available_video_chat_providers": { - "type": "object", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a supported [video call\nprovider](/help/configure-call-provider) that is configured on this\nserver and could be selected by an organization administrator.\n\nUseful for administrative settings UI that allows changing the realm\nsetting `video_chat_provider`.\n", - "additionalProperties": { - "description": "`{provider_name}`: Dictionary containing the details of the\nvideo call provider with the name of the chat provider as\nthe key.\n", - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "The name of the video call provider.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the video call provider.\n" - } - } - } - }, - "realm_presence_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether online presence of other users is shown in this\norganization.\n" - }, - "settings_send_digest_emails": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this Zulip server is configured to allow organizations to\nenable [digest emails](/help/digest-emails).\n\nRelevant for administrative settings UI that can change the digest\nemail settings.\n" - }, - "realm_email_auth_enabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization has enabled Zulip's default email and password\nauthentication feature. Determines whether Zulip stores a password\nfor the user and clients should offer any UI for changing the user's\nZulip password.\n" - }, - "realm_password_auth_enabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization allows any sort of password-based\nauthentication (whether via EmailAuthBackend or LDAP passwords).\n\nDetermines whether a client might ever need to display a password prompt\n(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)\nbefore presenting a login page).\n" - }, - "realm_push_notifications_enabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether push notifications are enabled for this organization. Typically\n`true` for Zulip Cloud and self-hosted realms that have a valid\nregistration for the [Mobile push notifications\nservice](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),\nand `false` for self-hosted servers that do not.\n\n**Changes**: Before Zulip 8.0 (feature level 231), this incorrectly was\n`true` for servers that were partly configured to use the Mobile Push\nNotifications Service but not properly registered.\n" - }, - "realm_push_notifications_enabled_end_timestamp": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nIf the server expects the realm's push notifications access to end at a\ndefinite time in the future, the UNIX timestamp (UTC) at which this is\nexpected to happen. Mobile clients should use this field to display warnings\nto users when the indicated timestamp is near.\n\n**Changes**: New in Zulip 8.0 (feature level 231).\n" - }, - "realm_upload_quota_mib": { - "type": "integer", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe total quota for uploaded files in this organization.\n\nClients are not responsible for checking this quota; it is included\nin the API only for display purposes.\n\nIf `null`, there is no limit.\n\n**Changes**: Before Zulip 9.0 (feature level 251), this field\nwas incorrectly measured in bytes, not MiB.\n\nNew in Zulip 5.0 (feature level 72). Previously,\nthis was called `realm_upload_quota`.\n" - }, - "realm_org_type": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe [organization type](/help/organization-type) for the realm.\nUseful only to clients supporting changing this setting for the\norganization, or clients implementing onboarding content or\nother features that varies with organization type.\n\n- 0 = Unspecified\n- 10 = Business\n- 20 = Open-source project\n- 30 = Education (non-profit)\n- 35 = Education (for-profit)\n- 40 = Research\n- 50 = Event or conference\n- 60 = Non-profit (registered)\n- 70 = Government\n- 80 = Political group\n- 90 = Community\n- 100 = Personal\n- 1000 = Other\n\n**Changes**: New in Zulip 6.0 (feature level 128).\n" - }, - "realm_plan_type": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe plan type of the organization.\n\n- 1 = Self-hosted organization (SELF_HOSTED)\n- 2 = Zulip Cloud free plan (LIMITED)\n- 3 = Zulip Cloud Standard plan (STANDARD)\n- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)\n" - }, - "realm_enable_guest_user_dm_warning": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether clients should show a warning when a user is composing\na DM to a guest user in this organization.\n\n**Changes**: New in Zulip 10.0 (feature level 348).\n" - }, - "realm_enable_guest_user_indicator": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether clients should display \"(guest)\" after the names of\nguest users to prominently highlight their status.\n\n**Changes**: New in Zulip 8.0 (feature level 216).\n" - }, - "realm_can_access_all_users_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to access all users in the\norganization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 314), this value used\nto be of type integer and did not accept anonymous user groups.\n\nNew in Zulip 8.0 (feature level 225).\n" - } - ] - }, - "realm_can_summarize_topics_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values) defining the\nset of users who are allowed to use AI summarization.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - } - ] - }, - "zulip_plan_is_not_limited": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the organization is using a limited (Zulip Cloud Free) plan.\n" - }, - "upgrade_text_for_wide_organization_logo": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nText to use when displaying UI for wide organization logos, a feature\nthat is currently not available on the Zulip Cloud Free plan.\n\nUseful only for clients supporting administrative UI for uploading\na new wide organization logo to brand the organization.\n" - }, - "realm_default_external_accounts": { - "type": "object", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a default external\naccount type that can be configured with Zulip's [custom\nprofile fields feature](/help/custom-profile-fields).\n\n**Changes**: New in Zulip 2.1.0.\n", - "additionalProperties": { - "description": "`{site_name}`: Dictionary containing the details of the\ndefault external account provider with the name of the\nwebsite as the key.\n", - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "The name of the external account provider\n" - }, - "text": { - "type": "string", - "description": "The text describing the external account.\n" - }, - "hint": { - "type": "string", - "description": "The help text to be displayed for the\ncustom profile field in user-facing\nsettings UI for configuring custom\nprofile fields for this account.\n" - }, - "url_pattern": { - "type": "string", - "description": "The regex pattern of the URL of a profile page\non the external site.\n" - } - } - } - }, - "jitsi_server_url": { - "type": "string", - "deprecated": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe base URL to be used to create Jitsi video calls. Equals\n`realm_jitsi_server_url || server_jitsi_server_url`.\n\n**Changes**: Deprecated in Zulip 8.0 (feature level 212) and will\neventually be removed. Previously, the Jitsi server to use was not\nconfigurable on a per-realm basis, and this field contained the server's\nconfigured Jitsi server. (Which is now provided as\n`server_jitsi_server_url`). Clients supporting older versions should fall\nback to this field when creating calls: using `realm_jitsi_server_url ||\nserver_jitsi_server_url` with newer servers and using `jitsi_server_url`\nwith servers below feature level 212.\n" - }, - "development_environment": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether this Zulip server is a development environment. Used\nto control certain features or UI (such as error popups)\nthat should only apply when connected to a Zulip development\nenvironment.\n" - }, - "server_generation": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA timestamp indicating when the process hosting this\nevent queue was started. Clients will likely only find\nthis value useful for inclusion in detailed error reports.\n" - }, - "password_min_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured minimum required length for passwords.\nNecessary for password change UI to show whether the password\nwill be accepted.\n" - }, - "password_max_length": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured maximum length for passwords.\nNecessary for password change UI to show whether the password\nwill be accepted.\n\n**Changes**: New in Zulip 10.0 (feature level 338).\n" - }, - "password_min_guesses": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThis Zulip server's configured minimum `zxcvbn` minimum guesses.\nNecessary for password change UI to show whether the password\nwill be accepted.\n" - }, - "giphy_rating_options": { - "type": "object", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nDictionary where each entry describes a valid rating\nthat is configured on this server and could be selected by an\norganization administrator.\n\nUseful for administrative settings UI that allows changing the\nallowed rating of GIFs.\n", - "additionalProperties": { - "description": "`{rating_name}`: Dictionary containing the details of the\nrating with the name of the rating as\nthe key.\n", - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "The description of the rating option.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the rating option.\n" - } - } - } - }, - "max_file_upload_size_mib": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum file size that can be uploaded to this Zulip organization.\n" - }, - "max_avatar_file_size_mib": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe maximum avatar size that can be uploaded to this Zulip server.\n" - }, - "server_inline_image_preview": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is configured with support for inline image previews.\nClients containing administrative UI for changing\n`realm_inline_image_preview` should consult this field before offering\nthat feature.\n" - }, - "server_inline_url_embed_preview": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is configured with support for inline URL previews.\nClients containing administrative UI for changing\n`realm_inline_url_embed_preview` should consult this field before offering\nthat feature.\n" - }, - "server_thumbnail_formats": { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nA list describing the image formats that uploaded\nimages will be thumbnailed into. Any image with a\nsource starting with `/user_uploads/thumbnail/` can\nhave its last path component replaced with any of the\nnames contained in this list, to obtain the desired\nthumbnail size.\n\n**Changes**: New in Zulip 9.0 (feature level 273).\n", - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "The file path component of the thumbnail format.\n" - }, - "max_width": { - "type": "integer", - "description": "The maximum width of this format.\n" - }, - "max_height": { - "type": "integer", - "description": "The maximum height of this format.\n" - }, - "format": { - "type": "string", - "description": "The extension of this format.\n" - }, - "animated": { - "type": "boolean", - "description": "If this file format is animated. These formats\nare only generated for uploaded imates which\nthemselves are animated.\n" - } - } - } - }, - "server_avatar_changes_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server allows avatar changes. Similar to\n`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`\nZulip server level setting.\n" - }, - "server_name_changes_disabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server allows name changes. Similar to\n`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`\nZulip server level setting.\n" - }, - "server_needs_upgrade": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nWhether the server is running an old version based on the Zulip\n[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),\nsuch that the web app will display to the current user a prominent warning.\n\n**Changes**: New in Zulip 5.0 (feature level 74).\n" - }, - "server_web_public_streams_enabled": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level\nsetting. A server that has disabled this setting intends to not offer [web\npublic channels](/help/public-access-option) to realms it hosts. (Zulip Cloud\ndefaults to `true`; self-hosted servers default to `false`).\n\nClients should use this to determine whether to offer UI for the\nrealm-level setting for enabling web-public channels\n(`realm_enable_spectator_access`).\n\n**Changes**: New in Zulip 5.0 (feature level 110).\n" - }, - "server_emoji_data_url": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL to a JSON file that describes which emoji names map to which\nemoji codes, for all Unicode emoji this Zulip server accepts.\n\nThe data at the given URL is a JSON object with one property, `code_to_names`.\nThe value of that property is a JSON object where each key is an\n[emoji code](/api/add-reaction#parameter-emoji_code) for an available\nUnicode emoji, and each value is the corresponding\n[emoji names](/api/add-reaction#parameter-emoji_name) for this emoji,\nwith the canonical name for the emoji always appearing first.\n\nThe HTTP response at that URL will have appropriate HTTP caching headers, such\nany HTTP implementation should get a cached version if emoji haven't changed\nsince the last request.\n\n**Changes**: New in Zulip 6.0 (feature level 140).\n" - }, - "server_jitsi_server_url": { - "type": "string", - "nullable": true, - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe URL of the Jitsi server that the Zulip server is configured to use by\ndefault; the organization-level setting `realm_jitsi_server_url` takes\nprecedence over this setting when both are set.\n\n**Changes**: New in Zulip 8.0 (feature level 212). Previously, this value\nwas available as the now-deprecated `jitsi_server_url`.\n" - }, - "server_can_summarize_topics": { - "type": "boolean", - "description": "Present if `realm` is present in `fetch_event_types`\n\nWhether topic summarization is enabled in the server or\nnot depending upon whether `TOPIC_SUMMARIZATION_MODEL`\nis set or not.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - }, - "event_queue_longpoll_timeout_seconds": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nRecommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.\nThis is guaranteed to be somewhat greater than the heartbeat frequency. It is important\nthat clients respect this parameter, so that increases in the heartbeat frequency do not\nbreak clients.\n\n**Changes**: New in Zulip 5.0 (feature level 74). Previously,\nthis was hardcoded to 90 seconds, and clients should use that as a fallback\nvalue when interacting with servers where this field is not present.\n" - }, - "realm_billing": { - "type": "object", - "additionalProperties": false, - "description": "Present if `realm_billing` is present in `fetch_event_types`.\n\nA dictionary containing billing information of the organization.\n\n**Changes**: New in Zulip 10.0 (feature level 363).\n", - "properties": { - "has_pending_sponsorship_request": { - "type": "boolean", - "description": "Whether there is a pending sponsorship request for the organization. Note that\nthis field will always be `false` if the user is not in `can_manage_billing_group`.\n\n**Changes**: New in Zulip 10.0 (feature level 363).\n" - } - } - }, - "realm_moderation_request_channel_id": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the private channel to which messages flagged by users for\nmoderation are sent. Moderators can use this channel to review and\nact on reported content.\n\nWill be `-1` if moderation requests are disabled.\n\nClients should check whether moderation requests are disabled to\ndetermine whether to present a \"report message\" feature in their UI\nwithin a given organization.\n\n**Changes**: New in Zulip 10.0 (feature level 331). Previously,\nno \"report message\" feature existed in Zulip.\n" - }, - "realm_new_stream_announcements_stream_id": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing the\n[creation of new channels][new-channel-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed 'realm_notifications_stream_id'\nto `realm_new_stream_announcements_stream_id`.\n" - }, - "realm_signup_announcements_stream_id": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing\nthat [new users have joined the organization][new-user-announce] are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n[new-user-announce]: /help/configure-automated-notices#new-user-announcements\n\n**Changes**: In Zulip 9.0 (feature level 241), renamed\n'realm_signup_notifications_stream_id' to `realm_signup_announcements_stream_id`.\n" - }, - "realm_zulip_update_announcements_stream_id": { - "type": "integer", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nThe ID of the channel to which automated messages announcing\nnew features or other end-user updates about the Zulip software are sent.\n\nWill be `-1` if such automated messages are disabled.\n\nSince these automated messages are sent by the server, this field is\nprimarily relevant to clients containing UI for changing it.\n\n**Changes**: New in Zulip 9.0 (feature level 242).\n" - }, - "realm_empty_topic_display_name": { - "type": "string", - "description": "Present if `realm` is present in `fetch_event_types`.\n\nClients declaring the `empty_topic_name` client capability\nshould use the value of `realm_empty_topic_display_name` to\ndetermine how to display the empty string topic.\n\nClients not declaring the `empty_topic_name` client capability\nreceive `realm_empty_topic_display_name` value as the topic name\nreplacing empty string.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously,\nthe empty string was not a valid topic name.\n" - }, - "realm_user_settings_defaults": { - "type": "object", - "additionalProperties": false, - "description": "Present if `realm_user_settings_defaults` is present in `fetch_event_types`.\n\nA dictionary containing the default values of settings for new users.\n\n**Changes**: New in Zulip 5.0 (feature level 95).\n", - "properties": { - "twenty_four_hour_time": { - "type": "boolean", - "nullable": true, - "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\nA `null` value indicates that the client should use the default time\nformat for the user's locale.\n\n**Changes**: Prior to Zulip 11.0 (feature level 408), `null`\nwas not a valid value for this setting. Note that it was not possible\nto actually set the time format to `null` at this feature level.\n\nNew in Zulip 5.0 (feature level 99). This value was previously\navailable as `realm_default_twenty_four_hour_time` in the top-level\nresponse object (only when `realm` was present in\n`fetch_event_types`).\n" - }, - "web_mark_read_on_scroll_policy": { - "type": "integer", - "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n" - }, - "web_channel_default_view": { - "type": "integer", - "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nIn Zulip 11.0 (feature level 383), we added a new option \"List of topics\"\nto this setting.\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n" - }, - "starred_message_counts": { - "type": "boolean", - "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n" - }, - "receives_typing_notifications": { - "type": "boolean", - "description": "Whether the user is configured to receive typing notifications from\nother users. The server will only deliver typing notifications events\nto users who for whom this is enabled.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were\nonly options to disable sending typing notifications.\n" - }, - "web_suggest_update_timezone": { - "type": "boolean", - "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n" - }, - "fluid_layout_width": { - "type": "boolean", - "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n" - }, - "high_contrast_mode": { - "type": "boolean", - "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n" - }, - "web_font_size_px": { - "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", - "type": "integer", - "example": 14 - }, - "web_line_height_percent": { - "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", - "type": "integer", - "example": 122 - }, - "color_scheme": { - "type": "integer", - "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n" - }, - "translate_emoticons": { - "type": "boolean", - "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n" - }, - "display_emoji_reaction_users": { - "type": "boolean", - "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting\nusers, rather than a count, for messages with few total\nreactions. The ideal cutoff may depend on the space\navailable for displaying reactions; the official web\napplication displays names when 3 or fewer total reactions\nare present with this setting enabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n" - }, - "default_language": { - "type": "string", - "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n" - }, - "web_home_view": { - "type": "string", - "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n" - }, - "web_escape_navigates_to_home_view": { - "type": "boolean", - "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n" - }, - "left_side_userlist": { - "type": "boolean", - "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n" - }, - "emojiset": { - "type": "string", - "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n" - }, - "demote_inactive_streams": { - "type": "integer", - "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n" - }, - "user_list_style": { - "type": "integer", - "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n" - }, - "web_animate_image_previews": { - "type": "string", - "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n" - }, - "web_stream_unreads_count_display_policy": { - "type": "integer", - "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n" - }, - "hide_ai_features": { - "type": "boolean", - "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - }, - "web_left_sidebar_show_channel_folders": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n" - }, - "web_left_sidebar_unreads_count_summary": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n" - }, - "enable_stream_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for channel messages.\n" - }, - "enable_stream_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for channel messages.\n" - }, - "enable_stream_push_notifications": { - "type": "boolean", - "description": "Enable mobile notifications for channel messages.\n" - }, - "enable_stream_audible_notifications": { - "type": "boolean", - "description": "Enable audible desktop notifications for channel messages.\n" - }, - "notification_sound": { - "type": "string", - "description": "Notification sound name.\n" - }, - "enable_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for direct messages and @-mentions.\n" - }, - "enable_sounds": { - "type": "boolean", - "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n" - }, - "enable_offline_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n" - }, - "enable_offline_push_notifications": { - "type": "boolean", - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n" - }, - "enable_online_push_notifications": { - "type": "boolean", - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n" - }, - "enable_followed_topic_desktop_notifications": { - "type": "boolean", - "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_email_notifications": { - "type": "boolean", - "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_push_notifications": { - "type": "boolean", - "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_followed_topic_audible_notifications": { - "type": "boolean", - "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "enable_digest_emails": { - "type": "boolean", - "description": "Enable digest emails when the user is away.\n" - }, - "enable_marketing_emails": { - "type": "boolean", - "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n" - }, - "enable_login_emails": { - "type": "boolean", - "description": "Enable email notifications for new logins to account.\n" - }, - "message_content_in_email_notifications": { - "type": "boolean", - "description": "Include the message's content in email notifications for new messages.\n" - }, - "pm_content_in_desktop_notifications": { - "type": "boolean", - "description": "Include content of direct messages in desktop notifications.\n" - }, - "wildcard_mentions_notify": { - "type": "boolean", - "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n" - }, - "enable_followed_topic_wildcard_mentions_notify": { - "type": "boolean", - "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n" - }, - "desktop_icon_count_display": { - "type": "integer", - "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,\nand followed topics` option, renumbering the options to insert it in\norder.\n" - }, - "realm_name_in_email_notifications_policy": { - "type": "integer", - "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n" - }, - "automatically_follow_topics_policy": { - "type": "integer", - "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "type": "integer", - "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n" - }, - "automatically_follow_topics_where_mentioned": { - "type": "boolean", - "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n" - }, - "resolved_topic_notice_auto_read_policy": { - "type": "string", - "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n" - }, - "presence_enabled": { - "type": "boolean", - "description": "Display the presence status to other users when online.\n" - }, - "enter_sends": { - "type": "boolean", - "description": "Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)\nin the compose box is enabled.\n" - }, - "enable_drafts_synchronization": { - "type": "boolean", - "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n" - }, - "email_notifications_batching_period_seconds": { - "type": "integer", - "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n" - }, - "available_notification_sounds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Array containing the names of the notification sound options\nsupported by this Zulip server. Only relevant to support UI\nfor configuring notification sounds.\n" - }, - "emojiset_choices": { - "description": "Array of dictionaries where each dictionary describes an emoji set\nsupported by this version of the Zulip server.\n\nOnly relevant to clients with configuration UI for choosing an emoji set;\nthe currently selected emoji set is available in the `emojiset` key.\n\nSee [PATCH /settings](/api/update-settings) for details on\nthe meaning of this setting.\n", - "type": "array", - "items": { - "type": "object", - "description": "Object describing a emoji set.\n", - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "description": "The key or the name of the emoji set which will be the value\nof `emojiset` if this emoji set is chosen.\n" - }, - "text": { - "type": "string", - "description": "The text describing the emoji set.\n" - } - } - } - }, - "send_private_typing_notifications": { - "type": "boolean", - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "send_stream_typing_notifications": { - "type": "boolean", - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "send_read_receipts": { - "type": "boolean", - "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n" - }, - "allow_private_data_export": { - "type": "boolean", - "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n" - }, - "email_address_visibility": { - "$ref": "#/components/schemas/EmailAddressVisibility" - }, - "web_navigate_to_sent_message": { - "type": "boolean", - "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n" - } - } - }, - "realm_users": { - "type": "array", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nA array of dictionaries where each entry describes a user\nwhose account has not been deactivated. Note that unlike\nthe usual User dictionary, this does not contain the `is_active`\nkey, as all the users present in this array have active accounts.\n\nIf the current user is a guest whose access to users is limited by a\n`can_access_all_users_group` policy, and the event queue was registered\nwith the `user_list_incomplete` client capability, then users that the\ncurrent user cannot access will not be included in this array. If the\ncurrent user's access to a user is restricted but the client lacks this\ncapability, then that inaccessible user will appear in the users array as\nan \"Unknown user\" object with the usual format but placeholder data whose\nonly variable content is the user ID.\n\nSee also `cross_realm_bots` and `realm_non_active_users`.\n\n**Changes**: Before Zulip 8.0 (feature level 232), the\n`user_list_incomplete` client capability did not exist, and so all\nclients whose access to a new user was prevented by\n`can_access_all_users_group` policy would receive a fake \"Unknown\nuser\" event for such users.\n", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "realm_non_active_users": { - "type": "array", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nA array of dictionaries where each entry describes a user\nwhose account has been deactivated. Note that unlike\nthe usual User dictionary this does not contain the `is_active`\nkey as all the users present in this array have deactivated\naccounts.\n", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "avatar_source": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe avatar data source type for the current user.\n\nValue values are `G` (gravatar) and `U` (uploaded by user).\n" - }, - "avatar_url_medium": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe avatar URL for the current user at 500x500 resolution, appropriate\nfor use in settings UI showing the user's avatar.\n" - }, - "avatar_url": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe URL of the avatar for the current user at 100x100\nresolution. See also `avatar_url_medium`.\n" - }, - "can_create_streams": { - "type": "boolean", - "deprecated": true, - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create at least one type\nof channel with the organization's [channel creation\npolicy](/help/configure-who-can-create-channels). Its value will\nalways equal `can_create_public_streams || can_create_private_streams`.\n\n**Changes**: Deprecated in Zulip 5.0 (feature level 102), when\nthe new `create_private_stream_policy` and\n`create_public_stream_policy` properties introduced the\npossibility that a user could only create one type of channel.\n\nThis field will be removed in a future release.\n" - }, - "can_create_public_streams": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create public channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\n**Changes**: New in Zulip 5.0 (feature level 102). In older\nversions, the deprecated `can_create_streams` property should be\nused to determine whether the user can create public channels.\n" - }, - "can_create_private_streams": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create private channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\n**Changes**: New in Zulip 5.0 (feature level 102). In older\nversions, the deprecated `can_create_streams` property should be\nused to determine whether the user can create private channels.\n" - }, - "can_create_web_public_streams": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to create public channels with\nthe organization's [channel creation policy](/help/configure-who-can-create-channels).\n\nNote that this will be false if the Zulip server does not have the\n`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has\nnot enabled the `enable_spectator_access` realm setting.\n\n**Changes**: New in Zulip 5.0 (feature level 103).\n" - }, - "can_subscribe_other_users": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is allowed to subscribe other users to channels with\nthe organization's [channels policy](/help/configure-who-can-invite-to-channels).\n" - }, - "can_invite_others_to_realm": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user [is allowed to invite others][who-can-send-invitations]\nto the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 51).\n\n[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations\n" - }, - "is_admin": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is at least an [organization administrator](/api/roles-and-permissions).\n" - }, - "is_owner": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is an [organization owner](/api/roles-and-permissions).\n\n**Changes**: New in Zulip 3.0 (feature level 11).\n" - }, - "is_moderator": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is at least an [organization moderator](/api/roles-and-permissions).\n\n**Changes**: Prior to Zulip 11.0 (feature level 380), this was only true\nfor users whose role was exactly the moderator role.\n\nNew in Zulip 4.0 (feature level 60).\n" - }, - "is_guest": { - "type": "boolean", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nWhether the current user is a [guest user](/api/roles-and-permissions).\n" - }, - "user_id": { - "type": "integer", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe unique ID for the current user.\n" - }, - "email": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe Zulip API email address for the current user. See also\n`delivery_email`; these may be the same or different depending\non the user's `email_address_visibility` policy.\n" - }, - "delivery_email": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe user's email address, appropriate for UI for changing\nthe user's email address. See also `email`.\n" - }, - "full_name": { - "type": "string", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nThe full name of the current user.\n" - }, - "cross_realm_bots": { - "type": "array", - "description": "Present if `realm_user` is present in `fetch_event_types`.\n\nArray of dictionaries where each dictionary contains details of\na single cross realm bot. Cross-realm bots are special system bot accounts\nlike Notification Bot.\n\nMost clients will want to combine this with `realm_users` in many\ncontexts.\n", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/UserBase" - }, - { - "additionalProperties": false, - "properties": { - "user_id": {}, - "delivery_email": {}, - "email": {}, - "full_name": {}, - "date_joined": {}, - "is_active": {}, - "is_owner": {}, - "is_admin": {}, - "is_guest": {}, - "is_bot": {}, - "is_system_bot": { - "type": "boolean", - "description": "Whether the user is a system bot. System bots are special\nbot user accounts that are managed by the system, rather than\nthe organization's administrators.\n\n**Changes**: This field was called `is_cross_realm_bot`\nbefore Zulip 5.0 (feature level 83).\n" - }, - "bot_type": { - "nullable": true - }, - "bot_owner_id": { - "nullable": true - }, - "role": {}, - "timezone": {}, - "avatar_url": { - "nullable": true - }, - "avatar_version": {}, - "profile_data": {} - } - } - ] - } - }, - "server_supported_permission_settings": { - "description": "Present if `realm` is present in `fetch_event_types`.\n\nMetadata detailing the valid values for permission settings that\nuse [group-setting values](/api/group-setting-values). Clients\nshould use these data as explained in the\n[main documentation](/api/group-setting-values#permitted-values)\nto determine what values to present as possible values for these\nsettings in UI components.\n\n**Changes**: Before Zulip 10.0 (feature level 326), this part of\nthe response had a documented-as-unstable format not suitable\nfor general client use, and should be ignored.\n\nNew in Zulip 8.0 (feature level 221).\n", - "type": "object", - "additionalProperties": false, - "properties": { - "realm": { - "type": "object", - "description": "Configuration for realm level group permission settings.\n", - "additionalProperties": { - "$ref": "#/components/schemas/GroupPermissionSetting" - } - }, - "stream": { - "type": "object", - "description": "Configuration for channel level group permission settings.\n", - "additionalProperties": { - "$ref": "#/components/schemas/GroupPermissionSetting" - } - }, - "group": { - "type": "object", - "description": "Configuration for group level group permission settings.\n", - "additionalProperties": { - "$ref": "#/components/schemas/GroupPermissionSetting" - } - } - } - }, - "max_bulk_new_subscription_messages": { - "description": "Maximum number of new subscribers for which the server will\nrespect the `send_new_subscription_messages` parameter when\n[adding subscribers to a channel](/api/subscribe#parameter-send_new_subscription_messages).\n\n**Changes**: New in Zulip 11.0 (feature level 397).\n", - "type": "number", - "example": 100 - } - }, - "example": { - "last_event_id": -1, - "msg": "", - "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", - "realm_emoji": { - "1": { - "author_id": 5, - "deactivated": false, - "id": "1", - "name": "green_tick", - "source_url": "/user_avatars/1/emoji/images/1.png" - }, - "2": { - "author_id": 3, - "deactivated": false, - "id": "2", - "name": "animated_img", - "source_url": "/user_avatars/1/emoji/images/animated_img.gif", - "still_url": "/user_avatars/1/emoji/images/still/animated_img.png" - } - }, - "result": "success", - "zulip_feature_level": 2, - "zulip_version": "5.0-dev-1650-gc3fd37755f", - "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c" - } - } - ] - } - } - } - } - } - } - }, - "/server_settings": { - "get": { - "operationId": "get-server-settings", - "summary": "Get server settings", - "tags": ["server_and_organizations"], - "x-response-description": "Please note that not all of these attributes are guaranteed to appear in a\nresponse, for two reasons:\n\n* This endpoint has evolved over time, so responses from older Zulip servers\n might be missing some keys (in which case a client should assume the\n appropriate default).\n* If a `/server_settings` request is made to the root domain of a\n multi-subdomain server, like the root domain of zulip.com, the settings\n that are realm-specific are not known and thus not provided.\n", - "description": "Fetch global settings for a Zulip server.\n\n**Note:** this endpoint does not require any authentication at all, and you can use it to check:\n\n- If this is a Zulip server, and if so, what version of Zulip it's running.\n- What a Zulip client (e.g. a mobile app or\n [zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to\n know in order to display a login prompt for the server (e.g. what\n authentication methods are available).\n", - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "authentication_methods": { - "type": "object", - "additionalProperties": false, - "deprecated": true, - "description": "Each key-value pair in the object indicates whether the authentication\nmethod is enabled on this server.\n\n**Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive\n`external_authentication_methods`.\n", - "properties": { - "password": { - "description": "Whether the user can authenticate using password.\n", - "type": "boolean" - }, - "dev": { - "description": "Whether the user can authenticate using development API key.\n", - "type": "boolean" - }, - "email": { - "description": "Whether the user can authenticate using email.\n", - "type": "boolean" - }, - "ldap": { - "description": "Whether the user can authenticate using LDAP.\n", - "type": "boolean" - }, - "remoteuser": { - "description": "Whether the user can authenticate using REMOTE_USER.\n", - "type": "boolean" - }, - "github": { - "description": "Whether the user can authenticate using their GitHub account.\n", - "type": "boolean" - }, - "azuread": { - "description": "Whether the user can authenticate using their Microsoft Entra ID account.\n", - "type": "boolean" - }, - "gitlab": { - "description": "Whether the user can authenticate using their GitLab account.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n", - "type": "boolean" - }, - "apple": { - "description": "Whether the user can authenticate using their Apple account.\n", - "type": "boolean" - }, - "google": { - "description": "Whether the user can authenticate using their Google account.\n", - "type": "boolean" - }, - "saml": { - "description": "Whether the user can authenticate using SAML.\n", - "type": "boolean" - }, - "openid connect": { - "description": "Whether the user can authenticate using OpenID Connect.\n", - "type": "boolean" - } - } - }, - "external_authentication_methods": { - "type": "array", - "description": "A list of dictionaries describing the available external\nauthentication methods (E.g. Google, GitHub, or SAML)\nenabled for this organization.\n\nThe list is sorted in the order in which these\nauthentication methods should be displayed.\n\n**Changes**: New in Zulip 2.1.0.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "A unique, table, machine-readable name for the authentication method,\nintended to be used by clients with special behavior for specific\nauthentication methods to correctly identify the method.\n" - }, - "display_name": { - "type": "string", - "description": "Display name of the authentication method, to be used in all buttons\nfor the authentication method.\n" - }, - "display_icon": { - "type": "string", - "nullable": true, - "description": "URL for an image to be displayed as an icon in all buttons for\nthe external authentication method.\n\nWhen `null`, no icon should be displayed.\n" - }, - "login_url": { - "type": "string", - "description": "URL to be used to initiate authentication using this method.\n" - }, - "signup_url": { - "type": "string", - "description": "URL to be used to initiate account registration using this method.\n" - } - } - } - }, - "zulip_feature_level": { - "type": "integer", - "description": "An integer indicating what features are\navailable on the server. The feature level increases monotonically;\na value of N means the server supports all API features introduced\nbefore feature level N. This is designed to provide a simple way\nfor client apps to decide whether the server supports a given\nfeature or API change. See the [changelog](/api/changelog) for\ndetails on what each feature level means.\n\n**Changes**: New in Zulip 3.0 (feature level 1). We recommend using an\nimplied value of 0 for Zulip servers that do not send this field.\n" - }, - "zulip_version": { - "type": "string", - "description": "The server's version number. This is often a release version number,\nlike `2.1.7`. But for a server running a [version from Git][git-release],\nit will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.\n\n[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions\n" - }, - "zulip_merge_base": { - "type": "string", - "description": "The `git merge-base` between `zulip_version` and official branches\nin the public\n[Zulip server and web app repository](https://github.com/zulip/zulip),\nin the same format as `zulip_version`. This will equal\n`zulip_version` if the server is not running a fork of the Zulip server.\n\nThis will be `\"\"` if unavailable.\n\n**Changes**: New in Zulip 5.0 (feature level 88).\n" - }, - "push_notifications_enabled": { - "type": "boolean", - "description": "Whether mobile/push notifications are configured.\n" - }, - "is_incompatible": { - "type": "boolean", - "description": "Whether the Zulip client that has sent a request to this endpoint is\ndeemed incompatible with the server.\n" - }, - "email_auth_enabled": { - "type": "boolean", - "description": "Setting for allowing users authenticate with an email-password\ncombination.\n" - }, - "require_email_format_usernames": { - "type": "boolean", - "description": "Whether all valid usernames for authentication to this\norganization will be email addresses. This is important\nfor clients to know whether to do client side validation\nof email address format in a login prompt.\n\nThis value will be false if the server has [LDAP\nauthentication][ldap-auth] enabled with a username and\npassword combination.\n\n[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory\n" - }, - "realm_uri": { - "type": "string", - "deprecated": true, - "description": "The organization's canonical URL. Alias of `realm_url`.\n\n**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term\n\"URI\" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).\n" - }, - "realm_url": { - "type": "string", - "description": "The organization's canonical URL.\n\n**Changes**: New in Zulip 9.0 (feature level 257), replacing the\ndeprecated `realm_uri`.\n" - }, - "realm_name": { - "type": "string", - "description": "The organization's name (for display purposes).\n" - }, - "realm_icon": { - "type": "string", - "description": "The URL for the organization's logo formatted as a square image,\nused for identifying the organization in small locations in the\nmobile and desktop apps.\n" - }, - "realm_description": { - "type": "string", - "description": "HTML description of the organization, as configured by the [organization\nprofile](/help/create-your-organization-profile).\n" - }, - "realm_web_public_access_enabled": { - "type": "boolean", - "description": "Whether the organization has enabled the creation of\n[web-public channels](/help/public-access-option) and\nat least one web-public channel on the server currently\nexists. Clients that support viewing content\nin web-public channels without an account can\nuse this to determine whether to offer that\nfeature on the login page for an organization.\n\n**Changes**: New in Zulip 5.0 (feature level 116).\n" - } - }, - "example": { - "authentication_methods": { - "password": true, - "dev": true, - "email": true, - "ldap": false, - "remoteuser": false, - "github": true, - "azuread": false, - "google": true, - "saml": true - }, - "zulip_version": "5.0-dev-1650-gc3fd37755f", - "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c", - "push_notifications_enabled": false, - "msg": "", - "is_incompatible": false, - "email_auth_enabled": true, - "require_email_format_usernames": true, - "realm_uri": "http://localhost:9991", - "realm_url": "http://localhost:9991", - "realm_name": "Zulip Dev", - "realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon", - "realm_description": "

The Zulip development environment default organization. It's great for testing!

", - "realm_web_public_access_enabled": false, - "result": "success", - "external_authentication_methods": [ - { - "name": "saml:idp_name", - "display_name": "SAML", - "display_icon": null, - "login_url": "/accounts/login/social/saml/idp_name", - "signup_url": "/accounts/register/social/saml/idp_name" - }, - { - "name": "google", - "display_name": "Google", - "display_icon": "/static/images/authentication_backends/googl_e-icon.png", - "login_url": "/accounts/login/social/google", - "signup_url": "/accounts/register/social/google" - }, - { - "name": "github", - "display_name": "GitHub", - "display_icon": "/static/images/authentication_backends/github-icon.png", - "login_url": "/accounts/login/social/github", - "signup_url": "/accounts/register/social/github" - } - ] - } - } - ] - } - } - } - } - } - } - }, - "/settings": { - "patch": { - "operationId": "update-settings", - "summary": "Update settings", - "tags": ["users"], - "description": "This endpoint is used to edit the current user's settings.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0\n(feature level 364) as we now have `web_font_size_px` and\n`web_line_height_percent` settings for more control.\n\nPrior to Zulip 5.0 (feature level 80), this endpoint only\nsupported the `full_name`, `email`, `old_password`, and\n`new_password` parameters. Notification settings were\nmanaged by `PATCH /settings/notifications`, and all other\nsettings by `PATCH /settings/display`.\n\nThe feature level 80 migration to merge these endpoints did not\nchange how request parameters are encoded. However, it did change\nthe handling of any invalid parameters present in a request\n(see feature level 78 change below).\n\nAs of feature level 80, the `PATCH /settings/display` and\n`PATCH /settings/notifications` endpoints are deprecated aliases\nfor this endpoint for backwards-compatibility, and will be removed\nonce clients have migrated to use this endpoint.\n\nPrior to Zulip 5.0 (feature level 78), this endpoint indicated\nwhich parameters it had processed by including in the response\nobject `\"key\": value` entries for values successfully changed by\nthe request. That was replaced by the more ergonomic\n[`ignored_parameters_unsupported`][ignored-parameters] array.\n\nThe `PATCH /settings/notifications` and `PATCH /settings/display`\nendpoints also had this behavior of indicating processed parameters\nbefore they became aliases of this endpoint in Zulip 5.0 (see\nfeature level 80 change above).\n\nBefore feature level 78, request parameters that were not supported\n(or were unchanged) were silently ignored.\n\n[ignored-parameters]: /api/rest-error-handling#ignored-parameters\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["left_side_userlist", "emojiset"] - } - } - ] - }, - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "full_name": { - "description": "A new display name for the user.\n", - "type": "string", - "example": "NewName" - }, - "email": { - "description": "Asks the server to initiate a confirmation sequence to change the user's email\naddress to the indicated value. The user will need to demonstrate control of the\nnew email address by clicking a confirmation link sent to that address.\n", - "type": "string", - "example": "newname@example.com" - }, - "old_password": { - "description": "The user's old Zulip password (or LDAP password, if LDAP authentication is in use).\n\nRequired only when sending the `new_password` parameter.\n", - "type": "string", - "example": "old12345" - }, - "new_password": { - "description": "The user's new Zulip password (or LDAP password, if LDAP authentication is in use).\n\nThe `old_password` parameter must be included in the request.\n", - "type": "string", - "example": "new12345" - }, - "twenty_four_hour_time": { - "description": "Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "web_mark_read_on_scroll_policy": { - "description": "Whether or not to mark messages as read when the user scrolls through their\nfeed.\n\n- 1 - Always\n- 2 - Only in conversation views\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no\nway for the user to configure this behavior on the web, and the Zulip web and\ndesktop apps behaved like the \"Always\" setting when marking messages as read.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "web_channel_default_view": { - "description": "Web/desktop app setting controlling the default navigation\nbehavior when clicking on a channel link.\n\n- 1 - Top topic in the channel\n- 2 - Channel feed\n- 3 - List of topics\n- 4 - Top unread topic in channel\n\n**Changes**: The \"Top unread topic in channel\" is new in Zulip 11.0\n(feature level 401).\n\nThe \"List of topics\" option is new in Zulip 11.0 (feature level 383).\n\nNew in Zulip 9.0 (feature level 269). Previously, this\nwas not configurable, and every user had the \"Channel feed\" behavior.\n", - "type": "integer", - "enum": [1, 2, 4], - "example": 1 - }, - "starred_message_counts": { - "description": "Whether clients should display the [number of starred\nmessages](/help/star-a-message#display-the-number-of-starred-messages).\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "receives_typing_notifications": { - "description": "Whether the user is configured to receive typing notifications from other users.\nThe server will only deliver typing notifications events to users who for whom this\nis enabled.\n\nBy default, this is set to true, enabling user to receive typing\nnotifications from other users.\n\n**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only\noptions to disable sending typing notifications.\n", - "type": "boolean", - "example": true - }, - "web_suggest_update_timezone": { - "type": "boolean", - "description": "Whether the user should be shown an alert, offering to update their\n[profile time zone](/help/change-your-timezone), when the time displayed\nfor the profile time zone differs from the current time displayed by the\ntime zone configured on their device.\n\n**Changes**: New in Zulip 10.0 (feature level 329).\n", - "example": true - }, - "fluid_layout_width": { - "description": "Whether to use the [maximum available screen width](/help/enable-full-width-display)\nfor the web app's center panel (message feed, recent conversations) on wide screens.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "high_contrast_mode": { - "description": "This setting is reserved for use to control variations in Zulip's design\nto help visually impaired users.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "web_font_size_px": { - "description": "User-configured primary `font-size` for the web application, in pixels.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was\nonly adjustable via browser zoom. Note that this setting was not fully\nimplemented at this feature level.\n", - "type": "integer", - "example": 14 - }, - "web_line_height_percent": { - "description": "User-configured primary `line-height` for the web application, in percent, so a\nvalue of 120 represents a `line-height` of 1.2.\n\n**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was\nnot user-configurable. Note that this setting was not fully implemented at this\nfeature level.\n", - "type": "integer", - "example": 122 - }, - "color_scheme": { - "description": "Controls which [color theme](/help/dark-theme) to use.\n\n- 1 - Automatic\n- 2 - Dark theme\n- 3 - Light theme\n\nAutomatic detection is implementing using the standard `prefers-color-scheme`\nmedia query.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "enable_drafts_synchronization": { - "description": "A boolean parameter to control whether synchronizing drafts is enabled for\nthe user. When synchronization is disabled, all drafts stored in the server\nwill be automatically deleted from the server.\n\nThis does not do anything (like sending events) to delete local copies of\ndrafts stored in clients.\n\n**Changes**: New in Zulip 5.0 (feature level 87).\n", - "type": "boolean", - "example": true - }, - "translate_emoticons": { - "description": "Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)\nin messages the user sends.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "display_emoji_reaction_users": { - "description": "Whether to display the names of reacting users on a message.\n\nWhen enabled, clients should display the names of reacting users, rather than\na count, for messages with few total reactions. The ideal cutoff may depend on\nthe space available for displaying reactions; the official web application\ndisplays names when 3 or fewer total reactions are present with this setting\nenabled.\n\n**Changes**: New in Zulip 6.0 (feature level 125).\n", - "type": "boolean", - "example": false - }, - "default_language": { - "description": "What [default language](/help/change-your-language) to use for the account.\n\nThis controls both the Zulip UI as well as email notifications sent to the user.\n\nThe value needs to be a standard language code that the Zulip server has\ntranslation data for; for example, `\"en\"` for English or `\"de\"` for German.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).\n", - "type": "string", - "example": "en" - }, - "web_home_view": { - "description": "The [home view](/help/configure-home-view) used when opening a new\nZulip web app window or hitting the `Esc` keyboard shortcut repeatedly.\n\n- \"recent_topics\" - Recent conversations view\n- \"inbox\" - Inbox view\n- \"all_messages\" - Combined feed view\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was\ncalled `default_view`, which was new in Zulip 4.0 (feature level 42).\n\nBefore Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", - "type": "string", - "example": "all_messages" - }, - "web_escape_navigates_to_home_view": { - "description": "Whether the escape key navigates to the\n[configured home view](/help/configure-home-view).\n\n**Changes**: New in Zulip 8.0 (feature level 219). Previously, this\nwas called `escape_navigates_to_default_view`, which was new in Zulip\n5.0 (feature level 107).\n", - "type": "boolean", - "example": true - }, - "left_side_userlist": { - "description": "Whether the users list on left sidebar in narrow windows.\n\nThis feature is not heavily used and is likely to be reworked.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "boolean", - "example": true - }, - "emojiset": { - "description": "The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),\nused to display emoji to the user everywhere they appear in the UI.\n\n- \"google\" - Google modern\n- \"google-blob\" - Google classic\n- \"twitter\" - Twitter\n- \"text\" - Plain text\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", - "type": "string", - "example": "google" - }, - "demote_inactive_streams": { - "description": "Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar.\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "user_list_style": { - "description": "The style selected by the user for the right sidebar user list.\n\n- 1 - Compact\n- 2 - With status\n- 3 - With avatar and status\n\n**Changes**: New in Zulip 6.0 (feature level 141).\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "web_animate_image_previews": { - "description": "Controls how animated images should be played in the message feed in the web/desktop application.\n\n- \"always\" - Always play the animated images in the message feed.\n- \"on_hover\" - Play the animated images on hover over them in the message feed.\n- \"never\" - Never play animated images in the message feed.\n\n**Changes**: New in Zulip 9.0 (feature level 275).\n", - "type": "string", - "enum": ["always", "on_hover", "never"], - "example": "on_hover" - }, - "web_stream_unreads_count_display_policy": { - "description": "Configuration for which channels should be displayed with a numeric unread count in the left sidebar.\nChannels that do not have an unread count will have a simple dot indicator for whether there are any\nunread messages.\n\n- 1 - All channels\n- 2 - Unmuted channels and topics\n- 3 - No channels\n\n**Changes**: New in Zulip 8.0 (feature level 210).\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 2 - }, - "hide_ai_features": { - "type": "boolean", - "description": "Controls whether user wants AI features like topic summarization to\nbe hidden in all Zulip clients.\n\n**Changes**: New in Zulip 10.0 (feature level 350).\n" - }, - "web_left_sidebar_show_channel_folders": { - "type": "boolean", - "description": "Determines whether the web/desktop application's left sidebar displays\nany channel folders configured by the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 411).\n", - "example": true - }, - "web_left_sidebar_unreads_count_summary": { - "description": "Determines whether the web/desktop application's left sidebar displays\nthe unread message count summary.\n\n**Changes**: New in Zulip 11.0 (feature level 398).\n", - "type": "boolean", - "example": true - }, - "timezone": { - "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/display` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).\n", - "type": "string", - "example": "Asia/Kolkata" - }, - "enable_stream_desktop_notifications": { - "description": "Enable visual desktop notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_stream_email_notifications": { - "description": "Enable email notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_stream_push_notifications": { - "description": "Enable mobile notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_stream_audible_notifications": { - "description": "Enable audible desktop notifications for channel messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "notification_sound": { - "description": "Notification sound name.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n\nUnnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).\n", - "type": "string", - "example": "ding" - }, - "enable_desktop_notifications": { - "description": "Enable visual desktop notifications for direct messages and @-mentions.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_sounds": { - "description": "Enable audible desktop notifications for direct messages and\n@-mentions.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "email_notifications_batching_period_seconds": { - "description": "The duration (in seconds) for which the server should wait to batch\nemail notifications before sending them.\n\n**Changes**: New in Zulip 5.0 (feature level 82)\n", - "type": "integer", - "example": 120 - }, - "enable_offline_email_notifications": { - "description": "Enable email notifications for direct messages and @-mentions received\nwhen the user is offline.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_offline_push_notifications": { - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is offline.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_online_push_notifications": { - "description": "Enable mobile notification for direct messages and @-mentions received\nwhen the user is online.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_desktop_notifications": { - "description": "Enable visual desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_email_notifications": { - "description": "Enable email notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_push_notifications": { - "description": "Enable push notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": false - }, - "enable_followed_topic_audible_notifications": { - "description": "Enable audible desktop notifications for messages sent to followed topics.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": false - }, - "enable_digest_emails": { - "description": "Enable digest emails when the user is away.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_marketing_emails": { - "description": "Enable marketing emails. Has no function outside Zulip Cloud.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_login_emails": { - "description": "Enable email notifications for new logins to account.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "message_content_in_email_notifications": { - "description": "Include the message's content in email notifications for new messages.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "pm_content_in_desktop_notifications": { - "description": "Include content of direct messages in desktop notifications.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "wildcard_mentions_notify": { - "description": "Whether wildcard mentions (E.g. @**all**) should send notifications\nlike a personal mention.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enable_followed_topic_wildcard_mentions_notify": { - "description": "Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics\nshould send notifications like a personal mention.\n\n**Changes**: New in Zulip 8.0 (feature level 189).\n", - "type": "boolean", - "example": true - }, - "desktop_icon_count_display": { - "description": "Unread count badge (appears in desktop sidebar and browser tab)\n\n- 1 - All unread messages\n- 2 - DMs, mentions, and followed topics\n- 3 - DMs and mentions\n- 4 - None\n\n**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed\ntopics` option, renumbering the options to insert it in order.\n\nBefore Zulip 5.0 (feature level 80), this setting was managed by the\n`PATCH /settings/notifications` endpoint.\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "realm_name_in_email_notifications_policy": { - "description": "Whether to [include organization name in subject of message notification\nemails](/help/email-notifications#include-organization-name-in-subject-line).\n\n- 1 - Automatic\n- 2 - Always\n- 3 - Never\n\n**Changes**: New in Zulip 7.0 (feature level 168), replacing the\nprevious `realm_name_in_notifications` boolean;\n`true` corresponded to `Always`, and `false` to `Never`.\n\nBefore Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications`\nsetting was managed by the `PATCH /settings/notifications` endpoint.\n", - "type": "integer", - "enum": [1, 2, 3], - "example": 1 - }, - "automatically_follow_topics_policy": { - "description": "Which [topics to follow automatically](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "description": "Which [topics to unmute automatically in muted channels](/help/mute-a-topic).\n\n- 1 - Topics the user participates in\n- 2 - Topics the user sends a message to\n- 3 - Topics the user starts\n- 4 - Never\n\n**Changes**: New in Zulip 8.0 (feature level 214).\n", - "type": "integer", - "enum": [1, 2, 3, 4], - "example": 1 - }, - "automatically_follow_topics_where_mentioned": { - "description": "Whether the server will automatically mark the user as following\ntopics where the user is mentioned.\n\n**Changes**: New in Zulip 8.0 (feature level 235).\n", - "type": "boolean", - "example": true - }, - "resolved_topic_notice_auto_read_policy": { - "description": "Controls whether the resolved-topic notices are marked as read.\n\n- \"always\" - Always mark resolved-topic notices as read.\n- \"except_followed\" - Mark resolved-topic notices as read in topics not followed by the user.\n- \"never\" - Never mark resolved-topic notices as read.\n\n**Changes**: New in Zulip 11.0 (feature level 385).\n", - "type": "string", - "enum": ["always", "except_followed", "never"], - "example": "except_followed" - }, - "presence_enabled": { - "description": "Display the presence status to other users when online.\n\n**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by\nthe `PATCH /settings/notifications` endpoint.\n", - "type": "boolean", - "example": true - }, - "enter_sends": { - "description": "Whether pressing Enter in the compose box sends a message\n(or saves a message edit).\n\n**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by\nthe `POST /users/me/enter-sends` endpoint, with the same parameter format.\n", - "type": "boolean", - "example": true - }, - "send_private_typing_notifications": { - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\ndirect messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "send_stream_typing_notifications": { - "description": "Whether [typing notifications](/help/typing-notifications) be sent when composing\nchannel messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "send_read_receipts": { - "description": "Whether other users are allowed to see whether you've\nread messages.\n\n**Changes**: New in Zulip 5.0 (feature level 105).\n", - "type": "boolean", - "example": true - }, - "allow_private_data_export": { - "description": "Whether organization administrators are allowed to\nexport your private data.\n\n**Changes**: New in Zulip 10.0 (feature level 293).\n", - "type": "boolean", - "example": true - }, - "email_address_visibility": { - "description": "The [policy][permission-level] this user has selected for [which other\nusers][help-email-visibility] in this organization can see their real\nemail address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n", - "type": "integer", - "enum": [1, 2, 3, 4, 5], - "example": 1 - }, - "web_navigate_to_sent_message": { - "description": "Web/desktop app setting for whether the user's view should\nautomatically go to the conversation where they sent a message.\n\n**Changes**: New in Zulip 9.0 (feature level 268). Previously,\nthis behavior was not configurable.\n", - "type": "boolean", - "example": true - } - } - }, - "encoding": { - "twenty_four_hour_time": { - "contentType": "application/json" - }, - "web_mark_read_on_scroll_policy": { - "contentType": "application/json" - }, - "web_channel_default_view": { - "contentType": "application/json" - }, - "starred_message_counts": { - "contentType": "application/json" - }, - "receives_typing_notifications": { - "contentType": "application/json" - }, - "web_suggest_update_timezone": { - "contentType": "application/json" - }, - "fluid_layout_width": { - "contentType": "application/json" - }, - "high_contrast_mode": { - "contentType": "application/json" - }, - "web_font_size_px": { - "contentType": "application/json" - }, - "web_line_height_percent": { - "contentType": "application/json" - }, - "color_scheme": { - "contentType": "application/json" - }, - "enable_drafts_synchronization": { - "contentType": "application/json" - }, - "translate_emoticons": { - "contentType": "application/json" - }, - "display_emoji_reaction_users": { - "contentType": "application/json" - }, - "web_escape_navigates_to_home_view": { - "contentType": "application/json" - }, - "left_side_userlist": { - "contentType": "application/json" - }, - "demote_inactive_streams": { - "contentType": "application/json" - }, - "user_list_style": { - "contentType": "application/json" - }, - "web_stream_unreads_count_display_policy": { - "contentType": "application/json" - }, - "hide_ai_features": { - "contentType": "application/json" - }, - "web_left_sidebar_show_channel_folders": { - "contentType": "application/json" - }, - "web_left_sidebar_unreads_count_summary": { - "contentType": "application/json" - }, - "enable_stream_desktop_notifications": { - "contentType": "application/json" - }, - "enable_stream_email_notifications": { - "contentType": "application/json" - }, - "enable_stream_push_notifications": { - "contentType": "application/json" - }, - "enable_stream_audible_notifications": { - "contentType": "application/json" - }, - "enable_desktop_notifications": { - "contentType": "application/json" - }, - "enable_sounds": { - "contentType": "application/json" - }, - "email_notifications_batching_period_seconds": { - "contentType": "application/json" - }, - "enable_offline_email_notifications": { - "contentType": "application/json" - }, - "enable_offline_push_notifications": { - "contentType": "application/json" - }, - "enable_online_push_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_desktop_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_email_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_push_notifications": { - "contentType": "application/json" - }, - "enable_followed_topic_audible_notifications": { - "contentType": "application/json" - }, - "enable_digest_emails": { - "contentType": "application/json" - }, - "enable_marketing_emails": { - "contentType": "application/json" - }, - "enable_login_emails": { - "contentType": "application/json" - }, - "message_content_in_email_notifications": { - "contentType": "application/json" - }, - "pm_content_in_desktop_notifications": { - "contentType": "application/json" - }, - "wildcard_mentions_notify": { - "contentType": "application/json" - }, - "enable_followed_topic_wildcard_mentions_notify": { - "contentType": "application/json" - }, - "desktop_icon_count_display": { - "contentType": "application/json" - }, - "realm_name_in_email_notifications_policy": { - "contentType": "application/json" - }, - "automatically_follow_topics_policy": { - "contentType": "application/json" - }, - "automatically_unmute_topics_in_muted_streams_policy": { - "contentType": "application/json" - }, - "automatically_follow_topics_where_mentioned": { - "contentType": "application/json" - }, - "presence_enabled": { - "contentType": "application/json" - }, - "enter_sends": { - "contentType": "application/json" - }, - "send_private_typing_notifications": { - "contentType": "application/json" - }, - "send_stream_typing_notifications": { - "contentType": "application/json" - }, - "send_read_receipts": { - "contentType": "application/json" - }, - "allow_private_data_export": { - "contentType": "application/json" - }, - "email_address_visibility": { - "contentType": "application/json" - }, - "web_navigate_to_sent_message": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SuccessIgnoredParameters" - } - } - } - }, - "/streams/{stream_id}/members": { - "get": { - "operationId": "get-subscribers", - "summary": "Get channel subscribers", - "tags": ["channels"], - "description": "Get all users subscribed to a channel.\n", - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "subscribers": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A list containing the IDs of all active users who are subscribed\nto the channel.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "subscribers": [11, 26] - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the requested channel does not exist,\nor where the user does not have permission to access the target channel:\n" - } - ] - } - } - } - } - } - } - }, - "/streams": { - "get": { - "operationId": "get-streams", - "summary": "Get all channels", - "tags": ["channels"], - "description": "Get all channels that the user [has access to](/help/channel-permissions).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": [""] - } - }, - { - "type": "include", - "parameters": { - "enum": ["include_public"] - }, - "description": "You may pass in one or more of the parameters mentioned below\nas URL query parameters, like so:\n" - } - ] - }, - "parameters": [ - { - "name": "include_public", - "in": "query", - "description": "Include all public channels.\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - { - "name": "include_web_public", - "in": "query", - "description": "Include all web-public channels.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - { - "name": "include_subscribed", - "in": "query", - "description": "Include all channels that the user is subscribed to.\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - { - "name": "exclude_archived", - "in": "query", - "description": "Whether to exclude archived streams from the results.\n\n**Changes**: New in Zulip 10.0 (feature level 315).\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": true - }, - { - "name": "include_all_active", - "in": "query", - "description": "Deprecated parameter to include all channels. The user must\nhave administrative privileges to use this parameter.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level\n356). Clients interacting with newer servers should use\nthe equivalent `include_all` parameter, which does not\nincorrectly hint that this parameter, and not\n`exclude_archived`, controls whether archived channels\nappear in the response.\n", - "schema": { - "type": "boolean", - "default": false - }, - "deprecated": true, - "example": true - }, - { - "name": "include_all", - "in": "query", - "description": "Include all channels that the user has metadata access to.\n\nFor organization administrators, this will be all channels\nin the organization, since organization administrators\nimplicitly have metadata access to all channels.\n\n**Changes**: New in Zulip 10.0 (feature level 356). On older\nversions, use `include_all_active`, which this replaces.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - { - "name": "include_default", - "in": "query", - "description": "Include all default channels for the user's realm.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - { - "name": "include_owner_subscribed", - "in": "query", - "description": "If the user is a bot, include all channels that the bot's owner is\nsubscribed to.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - { - "name": "include_can_access_content", - "in": "query", - "description": "Include all the channels that the user has content access to.\n\n**Changes**: New in Zulip 10.0 (feature level 356).\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "streams": { - "description": "A list of channel objects with details on the requested channels.\n", - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/BasicChannelBase" - }, - { - "additionalProperties": false, - "properties": { - "stream_id": {}, - "name": {}, - "is_archived": {}, - "description": {}, - "date_created": {}, - "creator_id": { - "nullable": true - }, - "invite_only": {}, - "rendered_description": {}, - "is_web_public": {}, - "stream_post_policy": {}, - "message_retention_days": { - "nullable": true - }, - "history_public_to_subscribers": {}, - "topics_policy": {}, - "first_message_id": { - "nullable": true - }, - "folder_id": { - "nullable": true - }, - "is_recently_active": {}, - "is_announcement_only": {}, - "can_add_subscribers_group": {}, - "can_remove_subscribers_group": {}, - "can_administer_channel_group": {}, - "can_delete_any_message_group": {}, - "can_delete_own_message_group": {}, - "can_move_messages_out_of_channel_group": {}, - "can_move_messages_within_channel_group": {}, - "can_send_message_group": {}, - "can_resolve_topics_group": {}, - "can_subscribe_group": {}, - "subscriber_count": {}, - "stream_weekly_traffic": { - "type": "integer", - "nullable": true, - "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, no information is provided on the average traffic.\nThis can be because the channel was recently created and there\nis insufficient data to make an estimate, or because the server\nwishes to omit this information for this client, this realm, or\nthis endpoint or type of event.\n\n**Changes**: New in Zulip 8.0 (feature level 199). Previously,\nthis statistic was available only in subscription objects.\n" - }, - "is_default": { - "type": "boolean", - "description": "Only present when [`include_default`][include_default]\nparameter is `true`.\n\nWhether the given channel is a\n[default channel](/help/set-default-channels-for-new-users).\n\n[include_default]: /api/get-streams#parameter-include_default\n" - } - }, - "required": [ - "stream_id", - "name", - "is_archived", - "description", - "date_created", - "creator_id", - "invite_only", - "rendered_description", - "is_web_public", - "stream_post_policy", - "message_retention_days", - "history_public_to_subscribers", - "first_message_id", - "folder_id", - "is_announcement_only", - "can_remove_subscribers_group", - "can_subscribe_group", - "stream_weekly_traffic", - "is_recently_active", - "subscriber_count" - ] - } - ] - } - } - }, - "example": { - "msg": "", - "result": "success", - "streams": [ - { - "can_add_subscribers_group": 10, - "can_remove_subscribers_group": 10, - "can_subscribe_group": 10, - "creator_id": null, - "date_created": 1691057093, - "description": "A private channel", - "first_message_id": 18, - "folder_id": 1, - "is_recently_active": true, - "history_public_to_subscribers": false, - "invite_only": true, - "is_announcement_only": false, - "is_archived": false, - "is_default": false, - "is_web_public": false, - "message_retention_days": null, - "name": "management", - "rendered_description": "

A private channel

", - "stream_id": 2, - "stream_post_policy": 1, - "stream_weekly_traffic": null, - "subscriber_count": 20 - }, - { - "can_add_subscribers_group": 9, - "can_remove_subscribers_group": 9, - "can_subscribe_group": 10, - "creator_id": 12, - "date_created": 1691057093, - "description": "A default public channel", - "first_message_id": 21, - "folder_id": null, - "is_recently_active": true, - "history_public_to_subscribers": true, - "invite_only": false, - "is_announcement_only": false, - "is_archived": false, - "is_default": true, - "is_web_public": false, - "message_retention_days": null, - "name": "welcome", - "rendered_description": "

A default public channel

", - "stream_id": 1, - "stream_post_policy": 1, - "stream_weekly_traffic": null, - "subscriber_count": 10 - } - ] - } - } - ] - } - } - } - } - } - } - }, - "/streams/{stream_id}": { - "get": { - "operationId": "get-stream-by-id", - "summary": "Get a channel by ID", - "tags": ["channels"], - "description": "Fetch details for the channel with the ID `stream_id`.\n\n**Changes**: New in Zulip 6.0 (feature level 132).\n", - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "stream": { - "$ref": "#/components/schemas/BasicChannel" - } - }, - "example": { - "msg": "", - "result": "success", - "stream": { - "description": "A Scandinavian country", - "first_message_id": 1, - "folder_id": 1, - "is_recently_active": true, - "history_public_to_subscribers": true, - "date_created": 1691057093, - "creator_id": null, - "invite_only": false, - "is_announcement_only": false, - "is_archived": false, - "is_web_public": false, - "message_retention_days": null, - "name": "Denmark", - "rendered_description": "

A Scandinavian country

", - "stream_id": 7, - "stream_post_policy": 1, - "can_add_subscribers_group": 2, - "can_remove_subscribers_group": 2, - "can_subscribe_group": 2, - "stream_weekly_traffic": null, - "subscriber_count": 12 - } - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the channel ID is not valid:\n" - } - ] - } - } - } - } - } - }, - "delete": { - "operationId": "archive-stream", - "summary": "Archive a channel", - "tags": ["channels"], - "description": "[Archive the channel](/help/archive-a-channel) with the ID `stream_id`.\n", - "x-requires-administrator": true, - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the supplied channel does not exist:\n" - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "update-stream", - "summary": "Update a channel", - "tags": ["channels"], - "description": "Configure the channel with the ID `stream_id`. This endpoint supports\nan organization administrator editing any property of a channel,\nincluding:\n\n- Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description)\n- Channel [permissions](/help/channel-permissions), including\n [privacy](/help/change-the-privacy-of-a-channel) and [who can\n send](/help/channel-posting-policy).\n\nNote that an organization administrator's ability to change a\n[private channel's permissions](/help/channel-permissions#private-channels)\ndepends on them being subscribed to the channel.\n\n**Changes**: Before Zulip 10.0 (feature level 362), channel privacy could not be\nedited for archived channels.\n\nRemoved `stream_post_policy` and `is_announcement_only`\nparameters in Zulip 10.0 (feature level 333), as permission to post\nin the channel is now controlled by `can_send_message_group`.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["new_name", "description", "is_private"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "description": { - "description": "The new [description](/help/change-the-channel-description) for\nthe channel, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 4.0 (feature level 64).\n", - "type": "string", - "example": "Discuss Italian history and travel destinations." - }, - "new_name": { - "description": "The new name for the channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 4.0 (feature level 64).\n", - "type": "string", - "example": "Italy" - }, - "is_private": { - "description": "Change whether the channel is a private channel.\n", - "type": "boolean", - "example": true - }, - "is_web_public": { - "description": "Change whether the channel is a web-public channel.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current use to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n\n**Changes**: New in Zulip 5.0 (feature level 98).\n", - "type": "boolean", - "example": true - }, - "history_public_to_subscribers": { - "description": "Whether the channel's message history should be available to\nnewly subscribed members, or users can only access messages\nthey actually received while subscribed to the channel.\n\nCorresponds to the shared history option for\n[private channels](/help/channel-permissions#private-channels).\n\nIt's an error for this parameter to be false for a public or\nweb-public channel and when is_private is false.\n\n**Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers`\nwas silently ignored unless the request also contained either `is_private` or\n`is_web_public`.\n", - "type": "boolean", - "example": false - }, - "is_default_stream": { - "description": "Add or remove the channel as a [default channel][default-channel]\nfor new users joining the organization.\n\n[default-channel]: /help/set-default-channels-for-new-users\n\n**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status\ncould only be changed using the [dedicated API endpoint](/api/add-default-stream).\n", - "type": "boolean", - "example": false - }, - "message_retention_days": { - "$ref": "#/components/schemas/MessageRetentionDays" - }, - "is_archived": { - "description": "A boolean indicating whether the channel is\n[archived](/help/archive-a-channel) or\nunarchived. Currently only allows unarchiving\npreviously archived channels.\n\n**Changes**: New in Zulip 11.0 (feature level 388).\n", - "type": "boolean", - "example": true - }, - "folder_id": { - "description": "ID of the new [channel folder](/help/channel-folders) to which the\nchannel should belong.\n\nA `null` value indicates the user wants to remove the channel from its\ncurrent channel folder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "type": "integer", - "nullable": true, - "example": 1 - }, - "topics_policy": { - "$ref": "#/components/schemas/TopicsPolicy" - }, - "can_add_subscribers_group": { - "allOf": [ - { - "description": "The set of users who have permission to add subscribers to this\nchannel expressed as an [update to a group-setting\nvalue][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nUsers who can administer the channel or have similar realm-level\npermissions can add subscribers to a public channel regardless\nof the value of this setting.\n\nUsers in this group need not be subscribed to a private channel to\nadd subscribers to it.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 342). Previously, there was no\nchannel-level setting for this permission.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_remove_subscribers_group": { - "allOf": [ - { - "description": "The set of users who have permission to unsubscribe others from this\nchannel expressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nOrganization administrators can unsubscribe others from a channel as though\nthey were in this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), channel administrators\ncould not unsubscribe other users if they were not an organization\nadministrator or part of `can_remove_subscribers_group`. Realm administrators\nwere not allowed to unsubscribe other users from a private channel if they\nwere not subscribed to that channel.\n\nPrior to Zulip 10.0 (feature level 320), this value was always the integer\nID of a system group.\n\nBefore Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`\nsetting was named `can_remove_subscribers_group_id`.\n\nNew in Zulip 7.0 (feature level 161).\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_administer_channel_group": { - "allOf": [ - { - "description": "The set of users who have permission to administer this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nOrganization administrators can administer every channel as though they were\nin this group without being explicitly listed here.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to add other subscribers to the channel.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349) a user needed to\n[have content access](/help/channel-permissions) to a channel in order\nto modify it. The exception to this rule was that organization\nadministrators can edit channel names and descriptions without having\nfull access to the channel.\n\nNew in Zulip 10.0 (feature level 325). Prior to this\nchange, the permission to administer channels was limited to realm\nadministrators.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_delete_any_message_group": { - "allOf": [ - { - "description": "The set of users who have permission to delete any message in the channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete any message in the channel.\n\nUsers present in the organization-level `can_delete_any_message_group` setting\ncan always delete any message in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in `can_delete_any_message_group` were able\ndelete any message in the organization.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_delete_own_message_group": { - "allOf": [ - { - "description": "The set of users who have permission to delete the messages that they have\nsent in the channel expressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete their own message in the channel.\n\nUsers with permission to delete any message in the channel\nand users present in the organization-level `can_delete_own_message_group` setting\ncan always delete their own messages in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in the organization-level `can_delete_any_message_group`\nand `can_delete_own_message_group` settings were able delete their own messages in\nthe organization.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_move_messages_out_of_channel_group": { - "allOf": [ - { - "description": "The set of users who have permission to move messages out of this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages out of the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_channels_group` setting can always move messages\nout of the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_channels_group` were able\nmove messages between channels.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_move_messages_within_channel_group": { - "allOf": [ - { - "description": "The set of users who have permission to move messages within this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages within the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_topics_group` setting can always move messages\nwithin the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_topics_group` were able\nmove messages between topics of a channel.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_send_message_group": { - "allOf": [ - { - "description": "The set of users who have permission to post in this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 333). Previously\n`stream_post_policy` field used to control the permission to\npost in the channel.\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_subscribe_group": { - "allOf": [ - { - "description": "The set of users who have permission to subscribe themselves to this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nEveryone, excluding guests, can subscribe to any public channel\nirrespective of this setting.\n\nUsers in this group can subscribe to a private channel as well.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 357).\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_resolve_topics_group": { - "allOf": [ - { - "description": "The set of users who have permission to to resolve topics in this channel\nexpressed as an [update to a group-setting value][update-group-setting].\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nUsers who have similar realm-level permissions can resolve topics\nin a channel regardless of the value of this setting.\n\n**Changes**: New in Zulip 11.0 (feature level 402).\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - } - } - }, - "encoding": { - "is_private": { - "contentType": "application/json" - }, - "is_web_public": { - "contentType": "application/json" - }, - "history_public_to_subscribers": { - "contentType": "application/json" - }, - "is_default_stream": { - "contentType": "application/json" - }, - "folder_id": { - "contentType": "application/json" - }, - "can_add_subscribers_group": { - "contentType": "application/json" - }, - "can_remove_subscribers_group": { - "contentType": "application/json" - }, - "can_administer_channel_group": { - "contentType": "application/json" - }, - "can_delete_any_message_group": { - "contentType": "application/json" - }, - "can_delete_own_message_group": { - "contentType": "application/json" - }, - "can_move_messages_out_of_channel_group": { - "contentType": "application/json" - }, - "can_move_messages_within_channel_group": { - "contentType": "application/json" - }, - "can_send_message_group": { - "contentType": "application/json" - }, - "can_subscribe_group": { - "contentType": "application/json" - }, - "can_resolve_topics_group": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the supplied channel does not exist:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid parameters", - "result": "error" - }, - "description": "An example JSON response for when invalid combination of channel permission\nparameters are passed:\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "A moderation request channel cannot be public.", - "result": "error" - }, - "description": "An example JSON response for when trying to set moderation request channel to\nbe public:\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/streams/{stream_id}/email_address": { - "get": { - "operationId": "get-stream-email-address", - "summary": "Get channel's email address", - "tags": ["channels"], - "description": "Get email address of a channel.\n\n**Changes**: New in Zulip 8.0 (feature level 226).\n", - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - }, - { - "name": "sender_id", - "in": "query", - "description": "The ID of a user or bot which should appear as the sender when messages\nare sent to the channel using the returned channel email address.\n\n`sender_id` can be:\n\n- ID of the current user.\n- ID of the Email gateway bot. (Default value)\n- ID of a bot owned by the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 335).\n\nPreviously, the sender was always Email gateway bot.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": false - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "email": { - "type": "string", - "description": "Email address of the channel.\n" - } - }, - "example": { - "result": "success", - "msg": "", - "email": "test.af64447e9e39374841063747ade8e6b0.show-sender@testserver" - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/InvalidChannelError" - }, - { - "description": "An example JSON response for when the requested channel does not exist,\nor where the user does not have permission to access the target channel:\n" - } - ] - } - } - } - } - } - } - }, - "/streams/{stream_id}/delete_topic": { - "post": { - "operationId": "delete-topic", - "summary": "Delete a topic", - "tags": ["channels"], - "description": "Delete all messages in a topic.\n\nTopics are a field on messages (not an independent data structure), so\ndeleting all the messages in the topic deletes the topic from Zulip.\n\nBecause this endpoint deletes messages in batches, it is possible for\nthe request to time out after only deleting some messages in the topic.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages in the topic were deleted, then the success\nresponse will return `\"complete\": true`.\n\n**Changes**: Before Zulip 9.0 (feature level 256), the server never sent\n[`stream` op: `update`](/api/get-events#stream-update) events with an\nupdated `first_message_id` for a channel when the oldest message that\nhad been sent to it changed.\n\nBefore Zulip 8.0 (feature level 211), if the server's\nprocessing was interrupted by a timeout, but some messages in the topic\nwere deleted, then it would return `\"result\": \"partially_completed\"`,\nalong with a `code` field for an error string, in the success response\nto indicate that there was a timeout and that the client should repeat\nthe request.\n\nAs of Zulip 6.0 (feature level 154), instead of returning an error\nresponse when a request times out after successfully deleting some of\nthe messages in the topic, a success response is returned with\n`\"result\": \"partially_completed\"` to indicate that some messages were\ndeleted.\n\nBefore Zulip 6.0 (feature level 147), this request did a single atomic\noperation, which could time out for very large topics. As of this\nfeature level, messages are deleted in batches, starting with the newest\nmessages, so that progress is made even if the request times out and\nreturns an error.\n", - "x-requires-administrator": true, - "parameters": [ - { - "$ref": "#/components/parameters/ChannelIdInPath" - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "topic_name": { - "description": "The name of the topic to delete.\n\nNote: When the value of `realm_empty_topic_display_name` found in\nthe [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n", - "type": "string", - "example": "new coffee machine" - } - }, - "required": ["topic_name"] - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "required": ["complete"], - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "complete": { - "type": "boolean", - "description": "Whether all unread messages were marked as read.\n\nWill be `false` if the request successfully marked\nsome, but not all, messages as read.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "complete": true - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Must be an organization administrator", - "code": "UNAUTHORIZED_PRINCIPAL" - }, - "description": "Error when the user does not have permission\nto delete topics in this organization:\n" - } - ] - } - } - } - } - } - } - }, - "/typing": { - "post": { - "operationId": "set-typing-status", - "summary": "Set \"typing\" status", - "tags": ["users"], - "description": "Notify other users whether the current user is\n[typing a message][help-typing].\n\nClients implementing Zulip's typing notifications\nprotocol should work as follows:\n\n- Send a request to this endpoint with `\"op\": \"start\"` when a user\n starts composing a message.\n- While the user continues to actively type or otherwise interact with\n the compose UI (e.g. interacting with the compose box emoji picker),\n send regular `\"op\": \"start\"` requests to this endpoint, using\n `server_typing_started_wait_period_milliseconds` in the\n [`POST /register`][api-register] response as the time interval\n between each request.\n- Send a request to this endpoint with `\"op\": \"stop\"` when a user\n has stopped using the compose UI for the time period indicated by\n `server_typing_stopped_wait_period_milliseconds` in the\n [`POST /register`][api-register] response or when a user\n cancels the compose action (if it had previously sent a \"start\"\n notification for that compose action).\n- Start displaying a visual typing indicator for a given conversation\n when a [`typing op:start`][start-typing] event is received\n from the server.\n- Continue displaying a visual typing indicator for the conversation\n until a [`typing op:stop`][stop-typing] event is received\n from the server or the time period indicated by\n `server_typing_started_expiry_period_milliseconds` in the\n [`POST /register`][api-register] response has passed without\n a new `typing \"op\": \"start\"` event for the conversation.\n\nThis protocol is designed to allow the server-side typing notifications\nimplementation to be stateless while being resilient as network failures\nwill not result in a user being incorrectly displayed as perpetually\ntyping.\n\nSee the subsystems documentation on [typing indicators][typing-protocol-docs]\nfor additional design details on Zulip's typing notifications protocol.\n\n**Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215)\nfor channel typing notifications, as no client actually implemented\nthe previous API for those.\n\nSupport for displaying channel typing notifications was new\nin Zulip 4.0 (feature level 58). Clients should indicate they support\nprocessing channel typing notifications via the `stream_typing_notifications`\nvalue in the `client_capabilities` parameter of the\n[`POST /register`][client-capabilities] endpoint.\n\n[help-typing]: /help/typing-notifications\n[api-register]: /api/register-queue\n[start-typing]: /api/get-events#typing-start\n[stop-typing]: /api/get-events#typing-stop\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n[typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["topic"] - } - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "type": { - "description": "Type of the message being composed.\n\n**Changes**: In Zulip 9.0 (feature level 248), `\"channel\"` was added as\nan additional value for this parameter to indicate a channel message is\nbeing composed.\n\nIn Zulip 8.0 (feature level 215), stopped supporting\n`\"private\"` as a valid value for this parameter.\n\nIn Zulip 7.0 (feature level 174), `\"direct\"` was added\nas the preferred way to indicate a direct message is being composed,\nbecoming the default value for this parameter and deprecating the\noriginal `\"private\"`.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n", - "type": "string", - "enum": ["direct", "stream", "channel"], - "default": "direct", - "example": "direct" - }, - "op": { - "description": "Whether the user has started (`\"start\"`) or stopped (`\"stop\"`) typing.\n", - "type": "string", - "enum": ["start", "stop"], - "example": "start" - }, - "to": { - "description": "User IDs of the recipients of the message being typed. Required for the\n`\"direct\"` type. Ignored in the case of `\"stream\"` or `\"channel\"` type.\n\nClients should send a JSON-encoded list of user IDs, even if there is only\none recipient.\n\n**Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter\nfor the `\"stream\"` type. Previously, in the case of the `\"stream\"` type, it\naccepted a single-element list containing the ID of the channel. A new parameter,\n`stream_id`, is now used for this. Note that the `\"channel\"` type did not\nexist at this feature level.\n\nSupport for typing notifications for channel' messages\nis new in Zulip 4.0 (feature level 58). Previously, typing\nnotifications were only for direct messages.\n\nBefore Zulip 2.0.0, this parameter accepted only a JSON-encoded\nlist of email addresses. Support for the email address-based format was\nremoved in Zulip 3.0 (feature level 11).\n", - "type": "array", - "items": { - "type": "integer" - }, - "minLength": 1, - "example": [9, 10] - }, - "stream_id": { - "description": "ID of the channel in which the message is being typed. Required for the `\"stream\"`\nor `\"channel\"` type. Ignored in the case of `\"direct\"` type.\n\n**Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element\nlist containing the ID of the channel was passed in `to` parameter.\n", - "type": "integer", - "example": 7 - }, - "topic": { - "description": "Topic to which message is being typed. Required for the `\"stream\"` or `\"channel\"`\ntype. Ignored in the case of `\"direct\"` type.\n\nNote: When `\"(no topic)\"` or the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response is used for this\nparameter, it is interpreted as an empty string.\n\n**Changes**: Before Zulip 10.0 (feature level 372),\n`\"(no topic)\"` was not interpreted as an empty string.\n\nBefore Zulip 10.0 (feature level 334), empty string\nwas not a valid topic name for channel messages.\n\nNew in Zulip 4.0 (feature level 58). Previously, typing notifications\nwere only for direct messages.\n", - "type": "string", - "example": "typing notifications" - } - }, - "required": ["op"] - }, - "encoding": { - "to": { - "contentType": "application/json" - }, - "stream_id": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Missing channel ID", - "result": "error" - }, - "description": "An example JSON error response when the user composes a channel message\nand `stream_id` is not specified:\n" - } - ] - } - } - } - } - } - } - }, - "/messages/{message_id}/typing": { - "post": { - "operationId": "set-typing-status-for-message-edit", - "summary": "Set \"typing\" status for message editing", - "tags": ["users"], - "description": "Notify other users whether the current user is editing a message.\n\nTyping notifications for editing messages follow the same protocol as\n[set-typing-status](/api/set-typing-status), see that endpoint for\ndetails.\n\n**Changes**: Before Zulip 10.0 (feature level 361), the endpoint was\nnamed `/message_edit_typing` with `message_id` a required parameter in\nthe request body. Clients are recommended to start using sending these\ntyping notifications starting from this feature level.\n\nNew in Zulip 10.0 (feature level 351). Previously, typing notifications were\nnot available when editing messages.\n", - "parameters": [ - { - "name": "message_id", - "in": "path", - "description": "The target message's ID.\n", - "schema": { - "type": "integer" - }, - "example": 47, - "required": true - } - ], - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "op": { - "description": "Whether the user has started (`\"start\"`) or stopped (`\"stop\"`) editing.\n", - "type": "string", - "enum": ["start", "stop"], - "example": "start" - } - }, - "required": ["op"] - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - } - }, - "/channels/create": { - "post": { - "tags": ["channels"], - "operationId": "create-channel", - "summary": "Create a channel", - "description": "Create a new [channel](/help/create-channels), and optionally subscribe\nusers to the newly created channel.\n\nThe initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\n**Changes**: New in Zulip 11.0 (feature level 417). Previously, this was\nonly possible via the [`POST /api/subscribe`](/api/subscribe) endpoint,\nwhich handles both channel subscription and creation.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "include", - "parameters": { - "enum": ["name", "subscribers"] - } - } - ] - }, - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the new channel.\n\nClients should use the `max_stream_name_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel name length.\n", - "example": "music" - }, - "description": { - "type": "string", - "description": "The [description](/help/change-the-channel-description)\nto use for the new channel being created, in text/markdown format.\n\nClients should use the `max_stream_description_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to\ndetermine the maximum channel description length.\n", - "example": "Channel for discussing all things music!" - }, - "subscribers": { - "description": "A list of user IDs of the users to be subscribed to the new channel.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [16, 12] - }, - "announce": { - "description": "This determines whether [notification bot](/help/configure-automated-notices)\nwill send an announcement about the new channel's creation.\n", - "type": "boolean", - "default": false, - "example": true - }, - "invite_only": { - "description": "This parameter and the ones that follow are used to request an initial\nconfiguration of the new channel.\n\nThis parameter determines whether the newly created channel will be\na [private channel](/help/channel-permissions#private-channels).\n", - "type": "boolean", - "default": false, - "example": true - }, - "is_web_public": { - "description": "This parameter determines whether the newly created channel will be\na web-public channel.\n\nNote that creating web-public channels requires the\n`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]\nto be enabled on the Zulip server in question, the organization\nto have enabled the `enable_spectator_access` realm setting, and\nthe current user to have permission under the organization's\n`can_create_web_public_channel_group` realm setting.\n\n[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html\n", - "type": "boolean", - "default": false, - "example": true - }, - "is_default_stream": { - "description": "This parameter determines whether the newly created channel will be\nadded as a [default channel][default-channels] for new users joining\nthe organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n", - "type": "boolean", - "default": false, - "example": true - }, - "folder_id": { - "description": "This parameter adds the newly created channel to the specified\n[channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "type": "integer", - "example": 1 - }, - "topics_policy": { - "$ref": "#/components/schemas/TopicsPolicy" - }, - "history_public_to_subscribers": { - "$ref": "#/components/schemas/HistoryPublicToSubscribers" - }, - "message_retention_days": { - "$ref": "#/components/schemas/MessageRetentionDays" - }, - "can_add_subscribers_group": { - "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" - }, - "can_delete_any_message_group": { - "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" - }, - "can_delete_own_message_group": { - "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" - }, - "can_remove_subscribers_group": { - "$ref": "#/components/schemas/CanRemoveSubscribersGroup" - }, - "can_administer_channel_group": { - "$ref": "#/components/schemas/CanAdministerChannelGroup" - }, - "can_move_messages_out_of_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" - }, - "can_move_messages_within_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" - }, - "can_send_message_group": { - "$ref": "#/components/schemas/CanSendMessageGroup" - }, - "can_subscribe_group": { - "$ref": "#/components/schemas/CanSubscribeGroup" - }, - "can_resolve_topics_group": { - "$ref": "#/components/schemas/CanResolveTopicsGroup" - } - }, - "required": ["name", "subscribers"] - }, - "encoding": { - "announce": { - "contentType": "application/json" - }, - "can_add_subscribers_group": { - "contentType": "application/json" - }, - "can_administer_channel_group": { - "contentType": "application/json" - }, - "can_move_messages_out_of_channel_group": { - "contentType": "application/json" - }, - "can_move_messages_within_channel_group": { - "contentType": "application/json" - }, - "can_remove_subscribers_group": { - "contentType": "application/json" - }, - "can_resolve_topics_group": { - "contentType": "application/json" - }, - "can_send_message_group": { - "contentType": "application/json" - }, - "can_subscribe_group": { - "contentType": "application/json" - }, - "subscribers": { - "contentType": "application/json" - }, - "invite_only": { - "contentType": "application/json" - }, - "is_web_public": { - "contentType": "application/json" - }, - "is_default_stream": { - "contentType": "application/json" - }, - "history_public_to_subscribers": { - "contentType": "application/json" - }, - "folder_id": { - "contentType": "application/json" - }, - "topics_policy": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "type": "object", - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "id": { - "type": "integer", - "description": "The ID of the newly created channel." - } - } - } - ], - "example": { - "result": "success", - "msg": "", - "id": 50 - } - } - } - } - }, - "409": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Channel 'discussions' already exists", - "code": "CHANNEL_ALREADY_EXISTS" - }, - "description": "An example JSON error response for when a channel with the submitted\nname already exists.\n" - } - ] - } - } - } - } - } - } - }, - "/user_groups/create": { - "post": { - "operationId": "create-user-group", - "summary": "Create a user group", - "tags": ["users"], - "description": "Create a new [user group](/help/user-groups).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The name of the user group.\n", - "type": "string", - "example": "marketing" - }, - "description": { - "description": "The description of the user group.\n", - "type": "string", - "example": "The marketing team." - }, - "members": { - "description": "An array containing the user IDs of the initial members for the\nnew user group.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [1, 2, 3, 4] - }, - "subgroups": { - "description": "An array containing the IDs of the initial subgroups for the new\nuser group.\n\nUser can add subgroups to the new group irrespective of other\npermissions for the new group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [11] - }, - "can_add_members_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 11 - }, - "can_join_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 11 - }, - "can_leave_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 15 - }, - "can_manage_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:everyone\"`\n[system groups][system-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[manage-user-groups]: /help/manage-user-groups\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 11 - }, - "can_mention_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:owners\"`\n[system groups][system-groups].\n\nBefore Zulip 9.0 (feature level 258), this parameter could only be the\ninteger form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this parameter was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 11 - }, - "can_remove_members_group": { - "allOf": [ - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ], - "example": 11 - } - }, - "required": ["name", "description", "members"] - }, - "encoding": { - "members": { - "contentType": "application/json" - }, - "subgroups": { - "contentType": "application/json" - }, - "can_add_members_group": { - "contentType": "application/json" - }, - "can_join_group": { - "contentType": "application/json" - }, - "can_leave_group": { - "contentType": "application/json" - }, - "can_manage_group": { - "contentType": "application/json" - }, - "can_mention_group": { - "contentType": "application/json" - }, - "can_remove_members_group": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "A success response containing the unique ID of the user group.\nThis field provides a straightforward way to reference the\nnewly created user group.\n\n**Changes**: New in Zulip 10.0 (feature level 317).\n", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": ["group_id"], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "group_id": { - "type": "integer", - "description": "The unique ID of the created user group.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "group_id": 123 - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "code": "BAD_REQUEST", - "msg": "Invalid user ID: 500" - }, - "description": "An example JSON error response for when the one of the users does not exist:\n" - } - ] - } - } - } - } - } - } - }, - "/user_groups/{user_group_id}/members": { - "post": { - "operationId": "update-user-group-members", - "summary": "Update user group members", - "tags": ["users"], - "description": "Update the members of a [user group](/help/user-groups). The\nuser IDs must correspond to non-deactivated users.\n\n**Changes**: Prior to Zulip 11.0 (feature level 391), members\ncould not be added or removed from a deactivated group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of\ndeactivated users were visible to the API and could be edited via this endpoint.\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["delete"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "delete": { - "description": "The list of user IDs to be removed from the user group.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [10] - }, - "add": { - "description": "The list of user IDs to be added to the user group.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [12, 13] - }, - "delete_subgroups": { - "description": "The list of user group IDs to be removed from the user group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [9] - }, - "add_subgroups": { - "description": "The list of user group IDs to be added to the user group.\n\n**Changes**: New in Zulip 10.0 (feature level 311).\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [9] - } - } - }, - "encoding": { - "delete": { - "contentType": "application/json" - }, - "add": { - "contentType": "application/json" - }, - "delete_subgroups": { - "contentType": "application/json" - }, - "add_subgroups": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - }, - "get": { - "operationId": "get-user-group-members", - "summary": "Get user group members", - "tags": ["users"], - "description": "Get the members of a [user group](/help/user-groups).\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - }, - { - "$ref": "#/components/parameters/DirectMemberOnly" - } - ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "members": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A list containing the user IDs of members of the user group.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "members": [10, 12] - } - } - ] - } - } - } - } - } - } - }, - "/user_groups/{user_group_id}": { - "patch": { - "operationId": "update-user-group", - "summary": "Update a user group", - "tags": ["users"], - "description": "Update the name, description or any of the permission settings\nof a [user group](/help/user-groups).\n\nThis endpoint is also used to reactivate a user group.\n\nNote that while permissions settings of deactivated groups can\nbe edited by this API endpoint, and those permissions settings\ndo affect the ability to modify the deactivated group and its\nmembership, the deactivated group itself cannot be mentioned\nor used in the value of any permission without first being reactivated.\n\n**Changes**: Starting with Zulip 11.0 (feature level 386), this\nendpoint can be used to reactivate a user group.\n\nPrior to Zulip 10.0 (feature level 340), only the name field\nof deactivated groups could be modified.\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The new name of the group.\n\n**Changes**: Before Zulip 7.0 (feature level 165), this was\na required field.\n", - "type": "string", - "example": "marketing team" - }, - "description": { - "description": "The new description of the group.\n\n**Changes**: Before Zulip 7.0 (feature level 165), this was\na required field.\n", - "type": "string", - "example": "The marketing team." - }, - "can_add_members_group": { - "allOf": [ - { - "description": "The set of users who have permission to add members to this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 11 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_join_group": { - "allOf": [ - { - "description": "The set of users who have permission to join this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 11 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_leave_group": { - "allOf": [ - { - "description": "The set of users who have permission to leave this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 15 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_manage_group": { - "allOf": [ - { - "description": "The set of users who have permission to [manage this user group][manage-user-groups]\nexpressed as an [update to a group-setting value][update-group-setting].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:everyone\"`\n[system groups][system-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[manage-user-groups]: /help/manage-user-groups\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 11 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_mention_group": { - "allOf": [ - { - "description": "The set of users who have permission to [mention this group][mentions],\nexpressed as an [update to a group-setting value][update-group-setting].\n\nThis setting cannot be set to `\"role:internet\"` and `\"role:owners\"`\n[system groups][system-groups].\n\n**Changes**: In Zulip 9.0 (feature level 260), this parameter was\nupdated to only accept an object with the `old` and `new` fields\ndescribed below. Prior to this feature level, this parameter could be\neither of the two forms of a [group-setting value][setting-values].\n\nBefore Zulip 9.0 (feature level 258), this parameter could only be the\ninteger form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this parameter was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\n[mentions]: /help/mention-a-user-or-group\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[setting-values]: /api/group-setting-values\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 11 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "can_remove_members_group": { - "allOf": [ - { - "description": "The set of users who have permission to remove members from this user group\nexpressed as an [update to a group-setting value][update-group-setting].\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n", - "example": { - "new": { - "direct_members": [10], - "direct_subgroups": [11] - }, - "old": 11 - } - }, - { - "$ref": "#/components/schemas/GroupSettingValueUpdate" - } - ] - }, - "deactivated": { - "description": "A deactivated user group can be reactivated by passing this\nparameter as `false`.\n\nPassing `true` does nothing as user group is deactivated\nusing [`POST /user_groups/{user_group_id}/deactivate`](deactivate-user-group)\nendpoint.\n\n**Changes**: New in Zulip 11.0 (feature level 386).\n", - "type": "boolean", - "example": false - } - } - }, - "encoding": { - "can_add_members_group": { - "contentType": "application/json" - }, - "can_join_group": { - "contentType": "application/json" - }, - "can_leave_group": { - "contentType": "application/json" - }, - "can_manage_group": { - "contentType": "application/json" - }, - "can_mention_group": { - "contentType": "application/json" - }, - "can_remove_members_group": { - "contentType": "application/json" - }, - "deactivated": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid user group", - "result": "error" - }, - "description": "An example JSON response when the user group ID is invalid:\n" - } - ] - } - } - } - } - } - } - }, - "/user_groups": { - "get": { - "operationId": "get-user-groups", - "summary": "Get user groups", - "tags": ["users"], - "description": "Fetches all of the user groups in the organization.\n\n!!! warn \"\"\n\n **Note**: This endpoint is only available to [members and\n administrators](/help/user-roles); bots and guests\n cannot use this endpoint.\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "include_deactivated_groups": { - "description": "Whether to include deactivated user groups in the response.\n\n**Changes**: In Zulip 10.0 (feature level 294), renamed\n`allow_deactivated` to `include_deactivated_groups`.\n\nNew in Zulip 10.0 (feature level 290). Previously, deactivated\nuser groups did not exist and thus would never be included in\nthe response.\n", - "type": "boolean", - "example": true, - "default": false - } - } - }, - "encoding": { - "allow_deactivated": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "user_groups": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "description": { - "type": "string", - "description": "The human-readable description of the user group.\n" - }, - "id": { - "type": "integer", - "description": "The user group's integer ID.\n" - }, - "date_created": { - "type": "integer", - "nullable": true, - "description": "The UNIX timestamp for when the user group was created, in UTC seconds.\n\nA `null` value means the user group has no recorded date, which is often\nbecause the group predates the metadata being tracked starting in Zulip 8.0,\nor because it was created via a data import tool\nor [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "creator_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who created this user group.\n\nA `null` value means the user group has no recorded creator, which is often\nbecause the group predates the metadata being tracked starting in Zulip 8.0,\nor because it was created via a data import tool\nor [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "members": { - "type": "array", - "description": "The integer user IDs of the user group's members, which\nare guaranteed to be non-deactivated users in the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this\nlist also included deactivated users who were members of\nthe user group before being deactivated.\n", - "items": { - "type": "integer" - } - }, - "direct_subgroup_ids": { - "type": "array", - "description": "The integer user group IDs of the direct subgroups.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nIntroduced in feature level 127 as `subgroups`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n", - "items": { - "type": "integer" - } - }, - "name": { - "type": "string", - "description": "User group name.\n" - }, - "is_system_group": { - "type": "boolean", - "description": "Whether the user group is a system group which cannot be\nmodified by users.\n\n**Changes**: New in Zulip 5.0 (feature level 93).\n" - }, - "can_add_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_join_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_leave_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_manage_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" - } - ] - }, - "can_mention_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" - } - ] - }, - "can_remove_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "deactivated": { - "type": "boolean", - "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" - } - } - }, - "description": "A list of `user_group` objects.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "user_groups": [ - { - "description": "Owners of this organization", - "id": 1, - "creator_id": null, - "date_created": null, - "name": "role:owners", - "members": [1], - "direct_subgroup_ids": [], - "is_system_group": true, - "can_add_members_group": 16, - "can_join_group": 16, - "can_leave_group": 15, - "can_manage_group": 16, - "can_mention_group": 11, - "can_remove_members_group": 16 - }, - { - "description": "Administrators of this organization, including owners", - "id": 2, - "creator_id": null, - "date_created": null, - "name": "role:administrators", - "members": [2], - "direct_subgroup_ids": [1], - "is_system_group": true, - "can_add_members_group": 17, - "can_join_group": 17, - "can_leave_group": 15, - "can_manage_group": 17, - "can_mention_group": 12, - "can_remove_members_group": 16 - }, - { - "description": "Characters of Hamlet", - "id": 3, - "creator_id": null, - "date_created": 1717484476, - "name": "hamletcharacters", - "members": [3, 4], - "direct_subgroup_ids": [], - "is_system_group": false, - "can_add_members_group": 20, - "can_join_group": 20, - "can_leave_group": 15, - "can_manage_group": 20, - "can_mention_group": 13, - "can_remove_members_group": 16 - } - ] - } - } - ] - } - } - } - } - } - } - }, - "/user_groups/{user_group_id}/subgroups": { - "post": { - "operationId": "update-user-group-subgroups", - "summary": "Update subgroups of a user group", - "tags": ["users"], - "description": "Update the subgroups of a [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 11.0 (feature level 391), subgroups\ncould not be added or removed from a deactivated group.\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", - "x-curl-examples-parameters": { - "oneOf": [ - { - "type": "exclude", - "parameters": { - "enum": ["delete"] - } - } - ] - }, - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "delete": { - "description": "The list of user group IDs to be removed from the user group.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [10] - }, - "add": { - "description": "The list of user group IDs to be added to the user group.\n", - "type": "array", - "items": { - "type": "integer" - }, - "example": [10] - } - } - }, - "encoding": { - "delete": { - "contentType": "application/json" - }, - "add": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - } - } - }, - "get": { - "operationId": "get-user-group-subgroups", - "summary": "Get subgroups of a user group", - "tags": ["users"], - "description": "Get the subgroups of a [user group](/help/user-groups).\n\n**Changes**: New in Zulip 6.0 (feature level 127).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - }, - { - "name": "direct_subgroup_only", - "in": "query", - "description": "Whether to consider only direct subgroups of the user group\nor subgroups of subgroups also.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true, - "required": false - } - ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "subgroups": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A list containing the IDs of subgroups of the user group.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "subgroups": [2, 3] - } - } - ] - } - } - } - } - } - } - }, - "/user_groups/{user_group_id}/members/{user_id}": { - "get": { - "operationId": "get-is-user-group-member", - "summary": "Get user group membership status", - "tags": ["users"], - "description": "Check whether a user is member of user group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303),\nthis would return true when passed a deactivated user\nwho was a member of the user group before being deactivated.\n\nNew in Zulip 6.0 (feature level 127).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - }, - { - "$ref": "#/components/parameters/UserId" - }, - { - "$ref": "#/components/parameters/DirectMemberOnly" - } - ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "is_user_group_member": { - "type": "boolean", - "description": "Whether the user is member of user group.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "is_user_group_member": false - } - } - ] - } - } - } - } - } - } - }, - "/user_groups/{user_group_id}/deactivate": { - "post": { - "operationId": "deactivate-user-group", - "summary": "Deactivate a user group", - "tags": ["users"], - "description": "Deactivate a user group. Deactivated user groups cannot be\nused for mentions, permissions, or any other purpose, but can\nbe reactivated or renamed.\n\nDeactivating user groups is preferable to deleting them from\nthe database, since the deactivation model allows audit logs\nof changes to sensitive group-valued permissions to be\nmaintained.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n", - "parameters": [ - { - "$ref": "#/components/parameters/UserGroupId" - } - ], - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid user group", - "result": "error" - }, - "description": "An example JSON response when the user group ID is invalid.\n" - } - ] - }, - { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "CANNOT_DEACTIVATE_GROUP_IN_USE", - "msg": "Cannot deactivate user group in use.", - "objections": [ - { - "type": "realm", - "settings": ["can_create_public_channel_group"] - } - ], - "result": "error" - }, - "description": "An example JSON response when the user group being deactivated\nis used for a setting or as a subgroup.\n\n**Changes**: New in Zulip 10.0 (feature level 298). Previously,\nthis error returned the `\"BAD_REQUEST\"` code.\n" - } - ] - } - ] - } - } - } - } - } - } - }, - "/channel_folders/create": { - "post": { - "operationId": "create-channel-folder", - "summary": "Create a channel folder", - "tags": ["channels"], - "x-requires-administrator": true, - "description": "Create a new [channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The name of the channel folder.\n\nClients should use the `max_channel_folder_name_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel folder name length.\n\nValue cannot be an empty string.\n", - "type": "string", - "example": "marketing" - }, - "description": { - "description": "The description of the channel folder.\n\nClients should use the `max_channel_folder_description_length`\nreturned by the [`POST /register`](/api/register-queue) endpoint\nto determine the maximum channel folder description length.\n\nNote that this parameter must be passed as part of the request,\nbut can be an empty string if no description for the new channel\nfolder is desired.\n", - "type": "string", - "example": "Channels for marketing." - } - }, - "required": ["name"] - } - } - } - }, - "responses": { - "200": { - "description": "A success response containing the unique ID of the channel folder.\nThis field provides a straightforward way to reference the\nnewly created channel folder.\n", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": ["channel_folder_id"], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "channel_folder_id": { - "type": "integer", - "description": "The unique ID of the created channel folder.\n" - } - }, - "example": { - "msg": "", - "result": "success", - "channel_folder_id": 12 - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "result": "error", - "msg": "Must be an organization administrator", - "code": "UNAUTHORIZED_PRINCIPAL" - }, - "description": "Error when the user does not have permission\nto create a channel folder:\n" - } - ] - } - } - } - } - } - } - }, - "/channel_folders": { - "get": { - "operationId": "get-channel-folders", - "summary": "Get channel folders", - "tags": ["channels"], - "description": "Fetches all of the [channel folders](/help/channel-folders) in the\norganization, sorted by the `order` field.\n\n**Changes**: Before Zulip 11.0 (feature level 414), the list of channel\nfolders was sorted by ID as the `order` field didn't exist.\n\nNew in Zulip 11.0 (feature level 389).\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "include_archived": { - "description": "Whether to include archived channel folders in the response.\n", - "type": "boolean", - "example": true, - "default": false - } - } - }, - "encoding": { - "include_archived": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "channel_folders": { - "type": "array", - "description": "A list of channel folder objects.\n", - "items": { - "$ref": "#/components/schemas/ChannelFolder" - } - } - }, - "example": { - "msg": "", - "result": "success", - "channel_folders": [ - { - "description": "Channels for frontend discussions", - "rendered_description": "

Channels for frontend discussions

", - "id": 1, - "creator_id": 1, - "date_created": 1691057093, - "name": "Frontend", - "is_archived": false - }, - { - "description": "Channels for **backend** discussions", - "rendered_description": "

Channels for backend discussions

", - "id": 2, - "creator_id": 1, - "date_created": 1791057093, - "name": "Backend", - "is_archived": false - } - ] - } - } - ] - } - } - } - } - } - }, - "patch": { - "operationId": "patch-channel-folders", - "summary": "Reorder channel folders", - "tags": ["channels"], - "x-requires-administrator": true, - "description": "Reorder the [channel folders](/help/channel-folders) in the user's\norganization.\n\nChannel folders are displayed in Zulip UI in order; this endpoint allows\nadministrative settings UI to change the ordering of channel folders.\n\nThis endpoint is used to implement the dragging feature described in the\n[manage channel folders documentation](/help/manage-channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 414).\n", - "requestBody": { - "required": true, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "order": { - "type": "array", - "description": "A list of channel folder IDs representing the new order.\n\nThis list must include the IDs of [all the organization's channel\nfolders](/api/get-channel-folders), including archived folders.\n", - "items": { - "type": "integer" - }, - "example": [2, 1] - } - }, - "required": ["order"] - }, - "encoding": { - "order": { - "contentType": "application/json" - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid order mapping", - "result": "error" - }, - "description": "An example JSON response when the order mapping is invalid:\n" - } - ] - } - } - } - } - } - } - }, - "/channel_folders/{channel_folder_id}": { - "patch": { - "operationId": "update-channel-folder", - "summary": "Update a channel folder", - "tags": ["channels"], - "x-requires-administrator": true, - "description": "Update the name or description of a [channel folder](/help/channel-folders)\nwith the specified ID.\n\nThis endpoint is also used to archive or unarchive the specified channel\nfolder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n", - "parameters": [ - { - "$ref": "#/components/parameters/ChannelFolderId" - } - ], - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "name": { - "description": "The new name of the channel folder.\n\nClients should use the `max_channel_folder_name_length` returned\nby the [`POST /register`](/api/register-queue) endpoint to determine\nthe maximum channel folder name length.\n\nValue cannot be an empty string.\n", - "type": "string", - "example": "backend" - }, - "description": { - "description": "The new description of the channel folder.\n\nClients should use the `max_channel_folder_description_length`\nreturned by the [`POST /register`](/api/register-queue) endpoint\nto determine the maximum channel folder description length.\n", - "type": "string", - "example": "Backend channels." - }, - "is_archived": { - "description": "Whether to archive or unarchive the channel folder.\n", - "type": "boolean", - "example": true - } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/SimpleSuccess" - }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "Invalid channel folder ID", - "result": "error" - }, - "description": "An example JSON response when the channel folder ID is invalid:\n" - } - ] - } - } - } - } - } - } - }, - "/real-time": { - "post": { - "tags": ["real_time_events"], - "description": "(Ignored)\n", - "requestBody": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "event_types": { - "$ref": "#/components/schemas/Event_types" - }, - "narrow": { - "$ref": "#/components/schemas/Narrow" - }, - "all_public_streams": { - "$ref": "#/components/schemas/AllPublicChannels" - } - } - }, - "encoding": { - "event_types": { - "contentType": "application/json" - }, - "narrow": { - "contentType": "application/json" - }, - "all_public_streams": { - "contentType": "application/json" - } - } - } - } - }, - "security": [ - { - "basicAuth": [] - } - ], - "responses": { - "200": { - "description": "Success" - } - } - } - }, - "/rest-error-handling": { - "post": { - "operationId": "rest-error-handling", - "summary": "Error handling", - "tags": ["real_time_events"], - "description": "Common error to many endpoints\n", - "responses": { - "400": { - "description": "Bad request.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/InvalidApiKeyError" - }, - { - "$ref": "#/components/schemas/MissingArgumentError" - }, - { - "$ref": "#/components/schemas/IncompatibleParametersError" - }, - { - "$ref": "#/components/schemas/UserNotAuthorizedError" - } - ] - } - } - } - }, - "401": { - "description": "Unauthorized.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/UserDeactivatedError" - }, - { - "$ref": "#/components/schemas/RealmDeactivatedError" - } - ] - } - } - } - }, - "429": { - "description": "Rate limit exceeded.\n", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RateLimitedError" - } - ] - } - } - } - } - } - } - }, - "/zulip-outgoing-webhook": { - "post": { - "operationId": "zulip-outgoing-webhooks", - "summary": "Outgoing webhooks", - "tags": ["webhooks"], - "description": "Outgoing webhooks allow you to build or set up Zulip integrations which are\nnotified when certain types of messages are sent in Zulip.\n", - "responses": { - "200": { - "description": "Success\n", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": false, - "description": "This is an example of the JSON payload that the Zulip server will `POST`\nto your server:\n", - "properties": { - "bot_email": { - "type": "string", - "description": "Email of the bot user.\n" - }, - "bot_full_name": { - "type": "string", - "description": "The full name of the bot user.\n" - }, - "data": { - "type": "string", - "description": "The message content, in raw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format (not rendered to HTML).\n" - }, - "trigger": { - "type": "string", - "description": "What aspect of the message triggered the outgoing webhook notification.\nPossible values include `direct_message` and `mention`.\n\n**Changes**: In Zulip 8.0 (feature level 201), renamed the trigger\n`private_message` to `direct_message`.\n" - }, - "token": { - "type": "string", - "description": "A string of alphanumeric characters that can be used to authenticate the\nwebhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot\nin the `zuliprc` file downloaded when creating the bot.\n" - }, - "message": { - "description": "A dictionary containing details on the message that triggered the\noutgoing webhook, in the format used by [`GET /messages`](/api/get-messages).\n", - "allOf": [ - { - "$ref": "#/components/schemas/MessagesBase" - }, - { - "additionalProperties": false, - "properties": { - "avatar_url": { - "nullable": true - }, - "client": {}, - "content": {}, - "content_type": {}, - "display_recipient": {}, - "edit_history": {}, - "id": {}, - "is_me_message": {}, - "last_edit_timestamp": {}, - "last_moved_timestamp": {}, - "reactions": {}, - "recipient_id": {}, - "sender_email": {}, - "sender_full_name": {}, - "sender_id": {}, - "sender_realm_str": {}, - "stream_id": {}, - "subject": {}, - "submessages": {}, - "timestamp": {}, - "topic_links": {}, - "type": {}, - "rendered_content": { - "type": "string", - "description": "The content/body of the message rendered in HTML.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - } - } - } - ] - } - }, - "example": { - "data": "@**Outgoing webhook test** Zulip is the world’s most productive group chat!", - "trigger": "mention", - "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0", - "message": { - "subject": "Verona2", - "sender_email": "iago@zulip.com", - "timestamp": 1527876931, - "client": "website", - "submessages": [], - "recipient_id": 20, - "topic_links": [], - "sender_full_name": "Iago", - "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1", - "rendered_content": "

@Outgoing webhook test Zulip is the world’s most productive group chat!

", - "sender_id": 5, - "stream_id": 5, - "content": "@**Outgoing webhook test** Zulip is the world’s most productive group chat!", - "display_recipient": "Verona", - "type": "stream", - "id": 112, - "is_me_message": false, - "reactions": [], - "sender_realm_str": "zulip" - }, - "bot_email": "outgoing-bot@localhost", - "bot_full_name": "Outgoing webhook test" - } - } - } - } - } - } - } - }, - "/calls/bigbluebutton/create": { - "get": { - "tags": ["channels"], - "operationId": "create-big-blue-button-video-call", - "summary": "Create BigBlueButton video call", - "description": "Create a video call URL for a BigBlueButton video call.\nRequires [BigBlueButton 2.4+](/integrations/doc/big-blue-button)\nto be configured on the Zulip server.\n\nThe acting user will be given the moderator role on the call.\n\n**Changes**: Prior to Zulip 10.0 (feature level 337), every\nuser was given the moderator role on BigBlueButton calls, via\nencoding a moderator password in the generated URLs.\n", - "parameters": [ - { - "in": "query", - "name": "meeting_name", - "schema": { - "type": "string" - }, - "required": true, - "description": "Meeting name for the BigBlueButton video call.\n", - "example": "test_channel meeting" - }, - { - "in": "query", - "name": "voice_only", - "schema": { - "type": "boolean" - }, - "required": false, - "description": "Configures whether the call is voice-only; if true,\ndisables cameras for all users. Only the call\ncreator/moderator can edit this configuration.\n\n**Changes**: New in Zulip 10.0 (feature level 337).\n", - "example": true - } - ], - "responses": { - "200": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "url": { - "description": "The URL for the BigBlueButton video call.\n", - "type": "string", - "example": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22" - } - }, - "example": { - "msg": "", - "result": "success", - "url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" - } - } - ] - } - } - } - } - } - } - } - }, - "components": { - "securitySchemes": { - "BasicAuth": { - "type": "http", - "scheme": "basic", - "description": "Basic authentication, with the user's email as the username, and the API\nkey as the password. The API key can be fetched using the\n`/fetch_api_key` or `/dev_fetch_api_key` endpoints.\n" - } - }, - "schemas": { - "IgnoredParametersUnsupported": { - "type": "array", - "items": { - "type": "string" - }, - "description": "An array of any parameters sent in the request that are not\nsupported by the endpoint.\n\nSee [error handling](/api/rest-error-handling#ignored-parameters) documentation\nfor details on this and its change history.\n" - }, - "EventIdSchema": { - "type": "integer", - "description": "The ID of the event. Events appear in increasing order but may not be consecutive.\n" - }, - "EventTypeSchema": { - "type": "string", - "description": "The event's type, relevant both for client-side dispatch and server-side\nfiltering by event type in [POST /register](/api/register-queue).\n" - }, - "Anchor": { - "type": "string" - }, - "Attachment": { - "type": "object", - "description": "Dictionary containing details of a file uploaded by a user.\n", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "The unique ID for the attachment.\n" - }, - "name": { - "type": "string", - "description": "Name of the uploaded file.\n" - }, - "path_id": { - "type": "string", - "description": "A representation of the path of the file within the\nrepository of user-uploaded files. If the `path_id` of a\nfile is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:\n`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.\n" - }, - "size": { - "type": "integer", - "description": "Size of the file in bytes.\n" - }, - "create_time": { - "type": "integer", - "description": "Time when the attachment was uploaded as a UNIX timestamp\nmultiplied by 1000 (matching the format of getTime() in JavaScript).\n\n**Changes**: Changed in Zulip 3.0 (feature level 22). This field was\npreviously a floating point number.\n" - }, - "messages": { - "type": "array", - "description": "Contains basic details on any Zulip messages that have been\nsent referencing this [uploaded file](/api/upload-file).\nThis includes messages sent by any user in the Zulip\norganization who sent a message containing a link to the\nuploaded file.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "date_sent": { - "type": "integer", - "description": "Time when the message was sent as a UNIX timestamp\nmultiplied by 1000 (matching the format of getTime() in JavaScript).\n\n**Changes**: Changed in Zulip 3.0 (feature level 22). This\nfield was previously strangely called `name` and was a floating\npoint number.\n" - }, - "id": { - "type": "integer", - "description": "The unique message ID. Messages should always be\ndisplayed sorted by ID.\n" - } - } - } - } - } - }, - "BasicChannel": { - "allOf": [ - { - "$ref": "#/components/schemas/BasicChannelBase" - }, - { - "additionalProperties": false, - "properties": { - "stream_id": {}, - "name": {}, - "is_archived": {}, - "description": {}, - "date_created": {}, - "creator_id": { - "nullable": true - }, - "invite_only": {}, - "rendered_description": {}, - "is_web_public": {}, - "stream_post_policy": {}, - "message_retention_days": { - "nullable": true - }, - "history_public_to_subscribers": {}, - "topics_policy": {}, - "first_message_id": { - "nullable": true - }, - "folder_id": { - "nullable": true - }, - "is_recently_active": {}, - "is_announcement_only": {}, - "can_add_subscribers_group": {}, - "can_remove_subscribers_group": {}, - "can_administer_channel_group": {}, - "can_delete_any_message_group": {}, - "can_delete_own_message_group": {}, - "can_move_messages_out_of_channel_group": {}, - "can_move_messages_within_channel_group": {}, - "can_send_message_group": {}, - "can_subscribe_group": {}, - "can_resolve_topics_group": {}, - "subscriber_count": {}, - "stream_weekly_traffic": { - "type": "integer", - "nullable": true, - "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, no information is provided on the average traffic.\nThis can be because the channel was recently created and there\nis insufficient data to make an estimate, or because the server\nwishes to omit this information for this client, this realm, or\nthis endpoint or type of event.\n\n**Changes**: New in Zulip 8.0 (feature level 199). Previously, this\nstatistic was available only in subscription objects.\n" - } - }, - "required": [ - "stream_id", - "name", - "is_archived", - "description", - "date_created", - "creator_id", - "invite_only", - "rendered_description", - "is_web_public", - "stream_post_policy", - "subscriber_count", - "message_retention_days", - "history_public_to_subscribers", - "first_message_id", - "folder_id", - "is_recently_active", - "is_announcement_only", - "can_remove_subscribers_group", - "stream_weekly_traffic", - "can_subscribe_group" - ] - } - ] - }, - "BasicChannelBase": { - "type": "object", - "description": "Object containing basic details about the channel.\n", - "properties": { - "stream_id": { - "type": "integer", - "description": "The unique ID of the channel.\n" - }, - "name": { - "type": "string", - "description": "The name of the channel.\n" - }, - "is_archived": { - "type": "boolean", - "description": "A boolean indicating whether the channel is [archived](/help/archive-a-channel).\n\n**Changes**: New in Zulip 10.0 (feature level 315).\nPreviously, this endpoint never returned archived channels.\n" - }, - "description": { - "type": "string", - "description": "The short description of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format,\nintended to be used to prepopulate UI for editing a channel's\ndescription.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "date_created": { - "type": "integer", - "description": "The UNIX timestamp for when the channel was created, in UTC seconds.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" - }, - "creator_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who created this channel.\n\nA `null` value means the channel has no recorded creator, which is often\nbecause the channel is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 9.0 (feature level 254).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "invite_only": { - "type": "boolean", - "description": "Specifies whether the channel is private or not.\nOnly people who have been invited can access a private channel.\n" - }, - "rendered_description": { - "type": "string", - "description": "The short description of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n" - }, - "is_web_public": { - "type": "boolean", - "description": "Whether the channel has been configured to allow unauthenticated\naccess to its message history from the web.\n\n**Changes**: New in Zulip 2.1.0.\n" - }, - "stream_post_policy": { - "type": "integer", - "deprecated": true, - "description": "A deprecated representation of a superset of the users who\nhave permission to post messages to the channel available\nfor backwards-compatibility. Clients should use\n`can_send_message_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can post.\n- 2 = Only administrators can post.\n- 3 = Only [full members][calc-full-member] can post.\n- 4 = Only moderators can post.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 333) and\nreplaced by `can_send_message_group`, which supports finer\nresolution of configurations, resulting in this property being\ninaccurate following that transition.\n\nNew in Zulip 3.0 (feature level 1), replacing the previous\n`is_announcement_only` boolean.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "message_retention_days": { - "type": "integer", - "nullable": true, - "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" - }, - "history_public_to_subscribers": { - "type": "boolean", - "description": "Whether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" - }, - "topics_policy": { - "$ref": "#/components/schemas/TopicsPolicy" - }, - "first_message_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the first message in the channel.\n\nIntended to help clients determine whether they need to display\nUI like the \"show all topics\" widget that would suggest the channel\nhas older history that can be accessed.\n\nIs `null` for channels with no message history.\n\n**Changes**: New in Zulip 2.1.0.\n" - }, - "folder_id": { - "$ref": "#/components/schemas/FolderId" - }, - "is_recently_active": { - "type": "boolean", - "description": "Whether the channel has recent message activity. Clients should use this to implement\n[hide inactive channels](/help/manage-inactive-channels) if\n`demote_inactive_streams` is enabled.\n\n**Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the\ndemote_inactive_streams from local message history, resulting in a choppy loading\nexperience.\n" - }, - "is_announcement_only": { - "type": "boolean", - "deprecated": true, - "description": "Whether the given channel is announcement only or not.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients\nshould use `stream_post_policy` instead.\n" - }, - "can_add_subscribers_group": { - "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" - }, - "can_remove_subscribers_group": { - "$ref": "#/components/schemas/CanRemoveSubscribersGroup" - }, - "can_administer_channel_group": { - "$ref": "#/components/schemas/CanAdministerChannelGroup" - }, - "can_delete_any_message_group": { - "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" - }, - "can_delete_own_message_group": { - "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" - }, - "can_move_messages_out_of_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" - }, - "can_move_messages_within_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" - }, - "can_send_message_group": { - "$ref": "#/components/schemas/CanSendMessageGroup" - }, - "can_subscribe_group": { - "$ref": "#/components/schemas/CanSubscribeGroup" - }, - "can_resolve_topics_group": { - "$ref": "#/components/schemas/CanResolveTopicsGroup" - }, - "subscriber_count": { - "type": "number", - "description": "The total number of non-deactivated users (including bots) who\nare subscribed to the channel. Clients are responsible for updating\nthis value using `peer_add` and `peer_remove` events.\n\nThe server's internals cannot guarantee this value is correctly\nsynced with `peer_add` and `peer_remove` events for the channel. As\na result, if a (rare) race occurs between a change in the channel's\nsubscribers and fetching this value, it is possible for a client\nthat is correctly following the events protocol to end up with a\npermanently off-by-one error in the channel's subscriber count.\n\nClients are recommended to fetch full subscriber data for a channel\nin contexts where it is important to avoid this risk. The official\nweb application, for example, uses this field primarily while\nwaiting to fetch a given channel's full subscriber list from the\nserver.\n\n**Changes**: New in Zulip 11.0 (feature level 394).\n" - } - } - }, - "BasicBot": { - "allOf": [ - { - "$ref": "#/components/schemas/BasicBotBase" - }, - { - "additionalProperties": false, - "properties": { - "user_id": {}, - "full_name": {}, - "api_key": {}, - "default_sending_stream": { - "nullable": true - }, - "default_events_register_stream": { - "nullable": true - }, - "default_all_public_streams": {}, - "avatar_url": {}, - "owner_id": { - "nullable": true - }, - "services": {}, - "is_active": { - "type": "boolean", - "description": "A boolean describing whether the user account has been deactivated.\n\n**Changes**: New in Zulip 8.0 (feature level 222). Previously\nwe sent `realm_user` event with `op` field set to `remove`\nwhen deactivating a bot and `realm_user` event with `op`\nfield set to `add` when reactivating a bot.\n" - } - } - } - ] - }, - "BasicBotBase": { - "type": "object", - "properties": { - "user_id": { - "type": "integer", - "description": "The user ID of the bot.\n" - }, - "full_name": { - "type": "string", - "description": "The full name of the bot.\n" - }, - "api_key": { - "type": "string", - "description": "The API key of the bot which it uses to make API requests.\n" - }, - "default_sending_stream": { - "type": "string", - "nullable": true, - "description": "The default sending channel of the bot. If `null`, the bot doesn't\nhave a default sending channel.\n" - }, - "default_events_register_stream": { - "type": "string", - "nullable": true, - "description": "The default channel for which the bot receives events/register data.\nIf `null`, the bot doesn't have such a default channel.\n" - }, - "default_all_public_streams": { - "type": "boolean", - "description": "Whether the bot can send messages to all channels by default.\n" - }, - "avatar_url": { - "type": "string", - "description": "The URL of the bot's avatar.\n" - }, - "owner_id": { - "type": "integer", - "nullable": true, - "description": "The user ID of the bot's owner.\n\nIf `null`, the bot has no owner.\n" - }, - "services": { - "type": "array", - "description": "An array containing extra configuration fields only relevant for\noutgoing webhook bots and embedded bots. This is always a single-element\narray.\n\nWe consider this part of the Zulip API to be unstable; it is used only\nfor UI elements for administering bots and is likely to change.\n", - "items": { - "description": "Object with extra configuration details for the bot. The fields in the\nobject depend on the type of bot.\n", - "oneOf": [ - { - "type": "object", - "additionalProperties": false, - "description": "When the bot is an outgoing webhook.\n", - "properties": { - "base_url": { - "type": "string", - "description": "The URL the outgoing webhook is configured to post to.\n" - }, - "token": { - "type": "string", - "description": "A unique token that the third-party service can use to confirm\nthat the request is indeed coming from Zulip.\n" - }, - "interface": { - "type": "integer", - "description": "An integer indicating what format requests are posted in:\n\n- 1 = Zulip's native outgoing webhook format.\n- 2 = Emulate the Slack outgoing webhook format.\n" - } - } - }, - { - "type": "object", - "additionalProperties": false, - "description": "When the bot is an embedded bot.\n", - "properties": { - "service_name": { - "type": "string", - "description": "The name of the bot.\n" - }, - "config_data": { - "$ref": "#/components/schemas/BotConfiguration" - } - } - } - ] - } - } - } - }, - "Bot": { - "allOf": [ - { - "$ref": "#/components/schemas/BasicBotBase" - }, - { - "description": "Object containing details of a bot.\n", - "additionalProperties": false, - "properties": { - "user_id": {}, - "full_name": {}, - "api_key": {}, - "default_sending_stream": { - "nullable": true - }, - "default_events_register_stream": { - "nullable": true - }, - "default_all_public_streams": {}, - "avatar_url": {}, - "owner_id": { - "nullable": true - }, - "services": {}, - "email": { - "type": "string", - "description": "The email of the bot.\n" - }, - "bot_type": { - "type": "integer", - "nullable": true, - "description": "An integer describing the type of bot:\n\n- `1` for a `Generic` bot.\n- `2` for an `Incoming webhook` bot.\n- `3` for an `Outgoing webhook` bot.\n- `4` for an `Embedded` bot.\n" - }, - "is_active": { - "type": "boolean", - "description": "A boolean describing whether the user account has been deactivated.\n" - } - } - } - ] - }, - "BotConfiguration": { - "type": "object", - "description": "A dictionary of string key/value pairs, which describe the configuration\nfor the bot. These are usually details like API keys, and are unique to\nthe integration/bot. Can be an empty dictionary.\n", - "additionalProperties": { - "description": "`{config_key}`: Description/value of the configuration data key.\n", - "type": "string" - } - }, - "WebhookConfigOption": { - "type": "array", - "description": "An array of configuration options that can be set when creating\na bot user for this incoming webhook integration.\n\nThis is an unstable API. Please discuss in chat.zulip.org before\nusing it.\n\n**Changes**: As of Zulip 11.0 (feature level 403), this\nobject is reserved for integration-specific configuration options\nthat can be set when creating a bot user. Previously, this object\nalso included optional webhook URL parameters, which are now\nspecified in the `url_options` object.\n\nBefore Zulip 10.0 (feature level 318), this field was named `config`,\nand was reserved for configuration data key-value pairs.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "description": "A key for the configuration option.\n" - }, - "label": { - "type": "string", - "description": "A human-readable label of the configuration option.\n" - }, - "validator": { - "type": "string", - "description": "The name of the validator function for the configuration\noption.\n" - } - } - } - }, - "WebhookUrlOption": { - "type": "array", - "description": "An array of optional URL parameter options for the incoming webhook\nintegration. In the web app, these are used when\n[generating a URL for an integration](/help/generate-integration-url).\n\nThis is an unstable API expected to be used only by the Zulip web\napp. Please discuss in chat.zulip.org before using it.\n\n**Changes**: New in Zulip 11.0 (feature level 403). Previously,\nthese optional URL parameter options were included in the\n`config_options` object.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "description": "The parameter variable to encode the users input for this\noption in the integrations webhook URL.\n" - }, - "label": { - "type": "string", - "description": "A human-readable label of the url option.\n" - }, - "validator": { - "type": "string", - "description": "The name of the validator function for the configuration\noption.\n" - } - } - } - }, - "CustomProfileField": { - "type": "object", - "additionalProperties": false, - "description": "Dictionary containing the details of a custom profile field configured\nfor this organization.\n", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the custom profile field. This will be referenced in the custom\nprofile fields section of user objects.\n" - }, - "type": { - "type": "integer", - "description": "An integer indicating the type of the custom profile field, which determines\nhow it is configured and displayed to users.\n\nSee the [Custom profile fields](/help/custom-profile-fields#profile-field-types)\narticle for details on what each type means.\n\n- **1**: Short text\n- **2**: Long text\n- **3**: List of options\n- **4**: Date picker\n- **5**: Link\n- **6**: Person picker\n- **7**: External account\n- **8**: Pronouns\n\n**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).\n" - }, - "order": { - "type": "integer", - "description": "Custom profile fields are displayed in both settings UI and\nUI showing users' profiles in increasing `order`.\n" - }, - "name": { - "type": "string", - "description": "The name of the custom profile field.\n" - }, - "hint": { - "type": "string", - "description": "The help text to be displayed for the custom profile field in user-facing\nsettings UI for configuring custom profile fields.\n" - }, - "field_data": { - "type": "string", - "description": "Field types 3 (List of options) and 7 (External account) support storing\nadditional configuration for the field type in the `field_data` attribute.\n\nFor field type 3 (List of options), this attribute is a JSON dictionary\ndefining the choices and the order they will be displayed in the\ndropdown UI for individual users to select an option.\n\nThe interface for field type 7 is not yet stabilized.\n" - }, - "display_in_profile_summary": { - "type": "boolean", - "description": "Whether the custom profile field, display or not on the user card.\n\nCurrently it's value not allowed to be `true` of `Long text` and `Person picker`\n[profile field types](/help/custom-profile-fields#profile-field-types).\n\nThis field is only included when its value is `true`.\n\n**Changes**: New in Zulip 6.0 (feature level 146).\n", - "default": false - }, - "required": { - "type": "boolean", - "description": "Whether an organization administrator has configured this profile field as\nrequired.\n\nBecause the required property is mutable, clients cannot assume that a required\ncustom profile field has a value. The Zulip web application displays a prominent\nbanner to any user who has not set a value for a required field.\n\n**Changes**: New in Zulip 9.0 (feature level 244).\n" - }, - "editable_by_user": { - "type": "boolean", - "description": "Whether regular users can edit this profile field on their own account.\n\nNote that organization administrators can edit custom profile fields for any user\nregardless of this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 296).\n", - "default": true - } - }, - "required": [ - "id", - "type", - "order", - "name", - "hint", - "required", - "editable_by_user" - ] - }, - "OnboardingStep": { - "type": "object", - "additionalProperties": false, - "description": "Dictionary containing details of a single onboarding step.\n", - "properties": { - "type": { - "type": "string", - "description": "The type of the onboarding step. Valid value is `\"one_time_notice\"`.\n\n**Changes**: Removed type `\"hotspot\"` in Zulip 9.0 (feature level 259).\n\nNew in Zulip 8.0 (feature level 233).\n" - }, - "name": { - "type": "string", - "description": "The name of the onboarding step.\n" - } - } - }, - "RealmAuthenticationMethod": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Boolean describing whether the authentication method (i.e. its key)\nis enabled in this organization.\n" - }, - "available": { - "type": "boolean", - "description": "Boolean describing whether the authentication method is available for use.\nIf false, the organization is not eligible to enable the authentication\nmethod.\n" - }, - "unavailable_reason": { - "type": "string", - "description": "Reason why the authentication method is unavailable. This field is optional\nand is only present when 'available' is false.\n" - } - }, - "additionalProperties": false, - "description": "Dictionary describing the properties of an authentication method for the\norganization - its enabled status and availability for use by the\norganization.\n" - }, - "RealmEmoji": { - "type": "object", - "additionalProperties": false, - "description": "`{emoji_id}`: Object containing details about the emoji with\nthe specified ID. It has the following properties:\n", - "properties": { - "id": { - "type": "string", - "description": "The ID for this emoji, same as the object's key.\n" - }, - "name": { - "type": "string", - "description": "The user-friendly name for this emoji. Users in the organization\ncan use this emoji by writing this name between colons (`:name :`).\n" - }, - "source_url": { - "type": "string", - "description": "The path relative to the organization's URL where the\nemoji's image can be found.\n" - }, - "still_url": { - "type": "string", - "nullable": true, - "description": "Only non-null when the emoji's image is animated.\n\nThe path relative to the organization's URL where a still\n(not animated) version of the emoji can be found. (This is\ncurrently always the first frame of the animation).\n\nThis is useful for clients to display the emoji in contexts\nwhere continuously animating it would be a bad user experience\n(E.g. because it would be distracting).\n\n**Changes**: New in Zulip 5.0 (added as optional field in\nfeature level 97 and then made mandatory, but nullable, in\nfeature level 113).\n" - }, - "deactivated": { - "type": "boolean", - "description": "Whether the emoji has been deactivated or not.\n" - }, - "author_id": { - "type": "integer", - "nullable": true, - "description": "The user ID of the user who uploaded the custom emoji.\nWill be `null` if the uploader is unknown.\n\n**Changes**: New in Zulip 3.0 (feature level 7). Previously\nwas accessible via an `author` object with an `id` field.\n" - } - } - }, - "RealmDomain": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of the newly added domain.\n", - "properties": { - "domain": { - "type": "string", - "description": "The new allowed domain.\n" - }, - "allow_subdomains": { - "type": "boolean", - "description": "Whether subdomains are allowed for this domain.\n" - } - } - }, - "RealmPlayground": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details about a realm playground.\n", - "properties": { - "id": { - "type": "integer", - "description": "The unique ID for the realm playground.\n" - }, - "name": { - "type": "string", - "description": "The user-visible display name of the playground. Clients\nshould display this in UI for picking which playground to\nopen a code block in, to differentiate between multiple\nconfigured playground options for a given pygments\nlanguage.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n" - }, - "pygments_language": { - "type": "string", - "description": "The name of the Pygments language lexer for that\nprogramming language.\n" - }, - "url_template": { - "type": "string", - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template for the playground. The template contains\nexactly one variable named `code`, which determines how the\nextracted code should be substituted in the playground URL.\n\n**Changes**: New in Zulip 8.0 (feature level 196). This replaced the\n`url_prefix` parameter, which was used to construct URLs by just\nconcatenating url_prefix and code.\n" - } - } - }, - "RealmExport": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details about a\n[data export](/help/export-your-organization).\n", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the data export.\n" - }, - "acting_user_id": { - "type": "integer", - "description": "The ID of the user who created the data export.\n" - }, - "export_time": { - "type": "number", - "description": "The UNIX timestamp of when the data export was started.\n" - }, - "deleted_timestamp": { - "type": "number", - "nullable": true, - "description": "The UNIX timestamp of when the data export was deleted.\n\nWill be `null` if the data export has not been deleted.\n" - }, - "failed_timestamp": { - "type": "number", - "nullable": true, - "description": "The UNIX timestamp of when the data export failed.\n\nWill be `null` if the data export succeeded, or if it's\nstill being generated.\n" - }, - "export_url": { - "type": "string", - "nullable": true, - "description": "The URL to download the generated data export.\n\nWill be `null` if the data export failed, or if it's\nstill being generated.\n" - }, - "pending": { - "type": "boolean", - "description": "Whether the data export is pending, which indicates it\nis still being generated, or if it succeeded, failed or\nwas deleted before being generated.\n\nDepending on the size of the organization, it can take\nanywhere from seconds to an hour to generate the data\nexport.\n" - }, - "export_type": { - "type": "integer", - "description": "Whether the data export is a public or a standard data export.\n\n- 1 = Public data export.\n- 2 = Standard data export.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nthe export type was not included in these objects because only\npublic data exports could be created or listed via the API or UI.\n" - } - } - }, - "UserGroup": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the user group's attributes.\n", - "properties": { - "name": { - "type": "string", - "description": "The name of the user group.\n" - }, - "date_created": { - "type": "integer", - "nullable": true, - "description": "The UNIX timestamp for when the user group was created, in UTC seconds.\n\nA `null` value means the user group has no recorded date, which is often\nbecause the user group is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "creator_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who created this user group.\n\nA `null` value means the user group has no recorded creator, which is often\nbecause the user group is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 10.0 (feature level 292).\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "description": { - "type": "string", - "description": "The description of the user group.\n" - }, - "members": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the ID of the users who are\nmembers of this user group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this\nlist also included deactivated users who were members of\nthe user group before being deactivated.\n" - }, - "direct_subgroup_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Array containing the ID of the direct_subgroups of\nthis user group.\n\n**Changes**: New in Zulip 6.0 (feature level 131).\nIntroduced in feature level 127 as `subgroups`, but\nclients can ignore older events as this feature level\npredates subgroups being fully implemented.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the user group.\n" - }, - "is_system_group": { - "type": "boolean", - "description": "Whether the user group is a system group which cannot be\ndirectly modified by users.\n\n**Changes**: New in Zulip 5.0 (feature level 93).\n" - }, - "can_add_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to add members to this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 305). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_join_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to join this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 301).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_leave_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to leave this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 308).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "can_manage_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [manage this user group][manage-user-groups].\n\n**Changes**: New in Zulip 10.0 (feature level 283).\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[manage-user-groups]: /help/manage-user-groups\n" - } - ] - }, - "can_mention_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to [mention this user group][mentions].\n\n**Changes**: Before Zulip 9.0 (feature level 258), this setting was\nalways the integer form of a [group-setting value][setting-values].\n\nBefore Zulip 8.0 (feature level 198), this setting was named\n`can_mention_group_id`.\n\nNew in Zulip 8.0 (feature level 191). Previously, groups could be\nmentioned only if they were not [system groups][system-groups].\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n[system-groups]: /api/group-setting-values#system-groups\n[mentions]: /help/mention-a-user-or-group\n" - } - ] - }, - "can_remove_members_group": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users who\nhave permission to remove members from this user group.\n\n**Changes**: New in Zulip 10.0 (feature level 324). Previously, this\npermission was controlled by the `can_manage_group` setting.\n\nWill be one of the following:\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "deactivated": { - "type": "boolean", - "description": "Whether the user group is deactivated. Deactivated groups\ncannot be used as a subgroup of another group or used for\nany other purpose.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" - } - } - }, - "GroupSettingValue": { - "oneOf": [ - { - "type": "integer", - "description": "The ID of the [user group](/help/user-groups) with this permission.\n" - }, - { - "type": "object", - "additionalProperties": false, - "properties": { - "direct_members": { - "description": "The list of IDs of individual users in the collection of users with this permission.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), this list would include\ndeactivated users who had the permission before being deactivated.\n", - "type": "array", - "items": { - "type": "integer" - } - }, - "direct_subgroups": { - "description": "The list of IDs of the groups in the collection of users with this permission.\n", - "type": "array", - "items": { - "type": "integer" - } - } - }, - "description": "An object with these fields:\n" - } - ] - }, - "GroupSettingValueUpdate": { - "type": "object", - "additionalProperties": false, - "properties": { - "new": { - "allOf": [ - { - "description": "The new [group-setting value](/api/group-setting-values) for who would\nhave this permission.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - }, - "old": { - "allOf": [ - { - "description": "The expected current [group-setting value](/api/group-setting-values)\nfor who has this permission.\n" - }, - { - "$ref": "#/components/schemas/GroupSettingValue" - } - ] - } - }, - "required": ["new"] - }, - "Invite": { - "type": "object", - "description": "A dictionary containing details about an [invitation](/help/invite-new-users).\n", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "The ID of the invitation.\n\nNote that email invitations and reusable invitation links are stored\nin different database tables on the server, so each ID is guaranteed\nto be unique in combination with the boolean value of `is_multiuse`,\ne.g. there can only be one invitation with `id: 1` and `is_multiuse:\ntrue`.\n" - }, - "invited_by_user_id": { - "type": "integer", - "description": "The [user ID](/api/get-user) of the user who created the invitation.\n\n**Changes**: New in Zulip 3.0 (feature level 22), replacing the `ref`\nfield which contained the Zulip display email address of the user who\ncreated the invitation.\n" - }, - "invited": { - "type": "integer", - "description": "The UNIX timestamp for when the invitation was created, in UTC seconds.\n" - }, - "expiry_date": { - "type": "integer", - "nullable": true, - "description": "The UNIX timestamp for when the invitation will expire, in UTC seconds.\nIf `null`, the invitation never expires.\n" - }, - "invited_as": { - "type": "integer", - "enum": [100, 200, 300, 400, 600], - "description": "The [organization-level role](/api/roles-and-permissions) of the user that\nis created when the invitation is accepted.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n" - }, - "email": { - "type": "string", - "description": "The email address the invitation was sent to. This will not be present when\n`is_multiuse` is `true` (i.e. the invitation is a reusable invitation link).\n" - }, - "notify_referrer_on_join": { - "type": "boolean", - "description": "A boolean indicating whether the referrer has opted to receive a direct\nmessage from [notification bot](/help/configure-automated-notices) when a user\naccount is created using this invitation.\n\n**Changes**: New in Zulip 9.0 (feature level 267). Previously,\nreferrers always received such direct messages.\n" - }, - "link_url": { - "type": "string", - "description": "The URL of the reusable invitation link. This will not be present when\n`is_multiuse` is `false` (i.e. the invitation is an email invitation).\n" - }, - "is_multiuse": { - "type": "boolean", - "description": "A boolean specifying whether the [invitation](/help/invite-new-users) is a\nreusable invitation link or an email invitation.\n" - } - } - }, - "InviteExpirationParameter": { - "description": "The number of minutes before the invitation will expire. If `null`, the\ninvitation will never expire. If unspecified, the server will use a default\nvalue (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which\ndefaults to 14400, i.e. 10 days) for when the invitation will expire.\n\n**Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an\n`invite_expires_in_days` parameter, which specified the duration in days instead\nof minutes.\n", - "type": "integer", - "nullable": true, - "example": 14400 - }, - "InviteRoleParameter": { - "description": "The [organization-level role](/api/roles-and-permissions) of the user that is\ncreated when the invitation is accepted.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\nUsers can only create invitation links for\n[roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels)\nas their own. For example, a moderator cannot invite someone to be an owner\nor administrator, but they can invite them to be a moderator or member.\n\n**Changes**: In Zulip 4.0 (feature level 61), added support for inviting\nusers as moderators.\n", - "type": "integer", - "enum": [100, 200, 300, 400, 600], - "default": 400, - "example": 600 - }, - "Subscription": { - "type": "object", - "additionalProperties": false, - "properties": { - "stream_id": { - "type": "integer", - "description": "The unique ID of a channel.\n" - }, - "name": { - "type": "string", - "description": "The name of a channel.\n" - }, - "description": { - "type": "string", - "description": "The [description](/help/change-the-channel-description) of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format,\nintended to be used to prepopulate UI for editing a channel's\ndescription.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n\nSee also `rendered_description`.\n" - }, - "rendered_description": { - "type": "string", - "description": "The [description](/help/change-the-channel-description) of the channel rendered as HTML, intended to\nbe used when displaying the channel description in a UI.\n\nOne should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax\nwork correctly. And any client-side security logic for\nuser-generated message content should be applied when displaying\nthis HTML as though it were the body of a Zulip message.\n\nSee also `description`.\n" - }, - "date_created": { - "type": "integer", - "description": "The UNIX timestamp for when the channel was created, in UTC seconds.\n\n**Changes**: New in Zulip 4.0 (feature level 30).\n" - }, - "creator_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who created this channel.\n\nA `null` value means the channel has no recorded creator, which is often\nbecause the channel is very old, or because it was created via a data\nimport tool or [management command][management-commands].\n\n**Changes**: New in Zulip 9.0 (feature level 254).\n\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" - }, - "invite_only": { - "type": "boolean", - "description": "Specifies whether the channel is private or not.\nOnly people who have been invited can access a private channel.\n" - }, - "subscribers": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "A list of user IDs of users who are also subscribed\nto a given channel. Included only if `include_subscribers` is `true`.\n" - }, - "partial_subscribers": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "If [`include_subscribers=\"partial\"`](/api/get-subscriptions#parameter-include_subscribers)\nwas requested, the server may, at its discretion, send a\n`partial_subscribers` list rather than a `subscribers` list\nfor channels with a large number of subscribers.\n\nThe `partial_subscribers` list contains an arbitrary\nsubset of the channel's subscribers that is guaranteed\nto include all bot user subscribers as well as all\nusers who have been active in the last 14 days, but\notherwise can be chosen arbitrarily by the server.\n\n**Changes**: New in Zulip 11.0 (feature level 412).\n" - }, - "desktop_notifications": { - "type": "boolean", - "nullable": true, - "description": "A boolean specifying whether desktop notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_desktop_notifications`, for\nthis channel.\n" - }, - "email_notifications": { - "type": "boolean", - "nullable": true, - "description": "A boolean specifying whether email notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_email_notifications`, for\nthis channel.\n" - }, - "wildcard_mentions_notify": { - "type": "boolean", - "nullable": true, - "description": "A boolean specifying whether wildcard mentions\ntrigger notifications as though they were personal\nmentions in this channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, wildcard_mentions_notify, for\nthis channel.\n" - }, - "push_notifications": { - "type": "boolean", - "nullable": true, - "description": "A boolean specifying whether push notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_push_notifications`, for\nthis channel.\n" - }, - "audible_notifications": { - "type": "boolean", - "nullable": true, - "description": "A boolean specifying whether audible notifications\nare enabled for the given channel.\n\nA `null` value means the value of this setting\nshould be inherited from the user-level default\nsetting, `enable_stream_audible_notifications`, for\nthis channel.\n" - }, - "pin_to_top": { - "type": "boolean", - "description": "A boolean specifying whether the given channel has been pinned\nto the top.\n" - }, - "is_muted": { - "type": "boolean", - "description": "Whether the user has muted the channel. Muted channels do\nnot count towards your total unread count and do not show\nup in the `Combined feed` view (previously known as `All messages`).\n\n**Changes**: Prior to Zulip 2.1.0, this feature was\nrepresented by the more confusingly named `in_home_view` (with the\nopposite value, `in_home_view=!is_muted`).\n" - }, - "in_home_view": { - "type": "boolean", - "deprecated": true, - "description": "Legacy property for if the given channel is muted, with inverted meaning.\n\n**Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted`\nwhere available.\n" - }, - "is_announcement_only": { - "type": "boolean", - "deprecated": true, - "description": "Whether only organization administrators can post to the channel.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients\nshould use `stream_post_policy` instead.\n" - }, - "is_web_public": { - "type": "boolean", - "description": "Whether the channel has been configured to allow unauthenticated\naccess to its message history from the web.\n" - }, - "color": { - "type": "string", - "description": "The user's personal color for the channel.\n" - }, - "stream_post_policy": { - "type": "integer", - "deprecated": true, - "description": "A deprecated representation of a superset of the users who\nhave permission to post messages to the channel available\nfor backwards-compatibility. Clients should use\n`can_send_message_group` instead.\n\nIt is an enum with the following possible values, corresponding\nto roles/system groups:\n\n- 1 = Any user can post.\n- 2 = Only administrators can post.\n- 3 = Only [full members][calc-full-member] can post.\n- 4 = Only moderators can post.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level 333) and\nreplaced by `can_send_message_group`, which supports finer\nresolution of configurations, resulting in this property being\ninaccurate following that transition.\n\nNew in Zulip 3.0 (feature level 1), replacing the previous\n`is_announcement_only` boolean.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" - }, - "message_retention_days": { - "type": "integer", - "nullable": true, - "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" - }, - "history_public_to_subscribers": { - "type": "boolean", - "description": "Whether the history of the channel is public to its subscribers.\n\nCurrently always true for public channels (i.e. `\"invite_only\": false` implies\n`\"history_public_to_subscribers\": true`), but clients should not make that\nassumption, as we may change that behavior in the future.\n" - }, - "first_message_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the first message in the channel.\n\nIntended to help clients determine whether they need to display\nUI like the \"show all topics\" widget that would suggest the channel\nhas older history that can be accessed.\n\nIs `null` for channels with no message history.\n" - }, - "folder_id": { - "$ref": "#/components/schemas/FolderId" - }, - "topics_policy": { - "$ref": "#/components/schemas/TopicsPolicy" - }, - "is_recently_active": { - "type": "boolean", - "description": "Whether the channel has recent message activity. Clients should use this to implement\n[hiding inactive channels](/help/manage-inactive-channels).\n\n**Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the\ndemote_inactive_streams from local message history, resulting in a choppy loading\nexperience.\n" - }, - "stream_weekly_traffic": { - "type": "integer", - "nullable": true, - "description": "The average number of messages sent to the channel per week, as\nestimated based on recent weeks, rounded to the nearest integer.\n\nIf `null`, the channel was recently created and there is\ninsufficient data to estimate the average traffic.\n" - }, - "can_add_subscribers_group": { - "$ref": "#/components/schemas/ChannelCanAddSubscribersGroup" - }, - "can_remove_subscribers_group": { - "$ref": "#/components/schemas/CanRemoveSubscribersGroup" - }, - "can_administer_channel_group": { - "$ref": "#/components/schemas/CanAdministerChannelGroup" - }, - "can_delete_any_message_group": { - "$ref": "#/components/schemas/CanDeleteAnyMessageGroup" - }, - "can_delete_own_message_group": { - "$ref": "#/components/schemas/CanDeleteOwnMessageGroup" - }, - "can_move_messages_out_of_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesOutOfChannelGroup" - }, - "can_move_messages_within_channel_group": { - "$ref": "#/components/schemas/CanMoveMessagesWithinChannelGroup" - }, - "can_send_message_group": { - "$ref": "#/components/schemas/CanSendMessageGroup" - }, - "can_subscribe_group": { - "$ref": "#/components/schemas/CanSubscribeGroup" - }, - "can_resolve_topics_group": { - "$ref": "#/components/schemas/CanResolveTopicsGroup" - }, - "is_archived": { - "type": "boolean", - "description": "A boolean indicating whether the channel is [archived](/help/archive-a-channel).\n\n**Changes**: New in Zulip 10.0 (feature level 315).\nPreviously, subscriptions only included active\nchannels. Note that some endpoints will never return archived\nchannels unless the client declares explicit support for\nthem via the `archived_channels` client capability.\n" - }, - "subscriber_count": { - "type": "number", - "description": "The total number of non-deactivated users (including bots) who\nare subscribed to the channel. Clients are responsible for updating\nthis value using `peer_add` and `peer_remove` events.\n\nThe server's internals cannot guarantee this value is correctly\nsynced with `peer_add` and `peer_remove` events for the channel. As\na result, if a (rare) race occurs between a change in the channel's\nsubscribers and fetching this value, it is possible for a client\nthat is correctly following the events protocol to end up with a\npermanently off-by-one error in the channel's subscriber count.\n\nClients are recommended to fetch full subscriber data for a channel\nin contexts where it is important to avoid this risk. The official\nweb application, for example, uses this field primarily while\nwaiting to fetch a given channel's full subscriber list from the\nserver.\n\n**Changes**: New in Zulip 11.0 (feature level 394).\n" - } - } - }, - "DefaultChannelGroup": { - "type": "object", - "description": "Dictionary containing details of a default channel\ngroup.\n", - "additionalProperties": false, - "properties": { - "name": { - "type": "string", - "description": "Name of the default channel group.\n" - }, - "description": { - "type": "string", - "description": "Description of the default channel group.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the default channel group.\n" - }, - "streams": { - "type": "array", - "description": "An array of IDs of all the channels in the default stream group.\n\n**Changes**: Before Zulip 10.0 (feature level 330), we sent array\nof dictionaries where each dictionary contained details about a\nsingle stream in the default stream group.\n", - "items": { - "type": "integer" - } - } - } - }, - "EmailAddressVisibility": { - "type": "integer", - "description": "The [policy][permission-level] for [which other users][help-email-visibility]\nin this organization can see the user's real email address.\n\n- 1 = Everyone\n- 2 = Members only\n- 3 = Administrators only\n- 4 = Nobody\n- 5 = Moderators only\n\n**Changes**: New in Zulip 7.0 (feature level 163), replacing the\nrealm-level setting.\n\n[permission-level]: /api/roles-and-permissions#permission-levels\n[help-email-visibility]: /help/configure-email-visibility\n" - }, - "EmojiReaction": { - "allOf": [ - { - "$ref": "#/components/schemas/EmojiBase" - }, - { - "additionalProperties": false, - "properties": { - "emoji_code": {}, - "emoji_name": {}, - "reaction_type": {}, - "user_id": { - "type": "integer", - "description": "The ID of the user who added the reaction.\n\n**Changes**: New in Zulip 3.0 (feature level 2). The `user`\nobject is deprecated and will be removed in the future.\n\nIn Zulip 10.0 (feature level 328), the deprecated `user` object\nwas removed which contained the following properties: `id`, `email`,\n`full_name` and `is_mirror_dummy`.\n" - } - } - } - ] - }, - "EmojiBase": { - "type": "object", - "properties": { - "emoji_name": { - "type": "string", - "description": "Name of the emoji.\n" - }, - "emoji_code": { - "type": "string", - "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n" - }, - "reaction_type": { - "type": "string", - "enum": ["unicode_emoji", "realm_emoji", "zulip_extra_emoji"], - "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n" - } - } - }, - "EmojiReactionEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/EmojiBase" - }, - { - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the user who added the reaction.\n\n**Changes**: New in Zulip 3.0 (feature level 2). The `user`\nobject is deprecated and will be removed in the future.\n" - }, - "user": { - "type": "object", - "additionalProperties": false, - "deprecated": true, - "description": "Dictionary with data on the user who added the\nreaction, including the user ID as the `user_id`\nfield.\n\n**Changes**: This field was re-added in Zulip 10.0 (feature\nlevel 339) after having been removed in Zulip 10.0 (feature\nlevel 328). It remains deprecated; it was re-added because the\nReact Native mobile app was still using it.\n\n**Deprecated** and to be removed in a future release once core\nclients have migrated to use the adjacent `user_id` field, which\nwas introduced in Zulip 3.0 (feature level 2). Clients\nsupporting older Zulip server versions should use the user ID\nmentioned in the description above as they would the `user_id`\nfield.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "ID of the user.\n" - }, - "email": { - "type": "string", - "description": "Zulip API email of the user.\n" - }, - "full_name": { - "type": "string", - "description": "Full name of the user.\n" - }, - "is_mirror_dummy": { - "type": "boolean", - "description": "Whether the user is a mirror dummy.\n" - } - } - } - } - } - ] - }, - "MessagesEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/MessagesBase" - }, - { - "additionalProperties": false, - "properties": { - "avatar_url": { - "nullable": true - }, - "client": {}, - "content": {}, - "content_type": {}, - "display_recipient": {}, - "edit_history": {}, - "id": {}, - "is_me_message": {}, - "last_edit_timestamp": {}, - "last_moved_timestamp": {}, - "reactions": {}, - "recipient_id": {}, - "sender_email": {}, - "sender_full_name": {}, - "sender_id": {}, - "sender_realm_str": {}, - "stream_id": {}, - "subject": {}, - "submessages": {}, - "timestamp": {}, - "topic_links": {}, - "type": {} - } - } - ] - }, - "MessagesBase": { - "type": "object", - "description": "Object containing details of the message.\n", - "properties": { - "avatar_url": { - "type": "string", - "nullable": true, - "description": "The URL of the message sender's avatar. Can be `null` only if\nthe current user has access to the sender's real email address\nand `client_gravatar` was `true`.\n\nIf `null`, then the sender has not uploaded an avatar in Zulip,\nand the client can compute the gravatar URL by hashing the\nsender's email address, which corresponds in this case to their\nreal email address.\n\n**Changes**: Before Zulip 7.0 (feature level 163), access to a\nuser's real email address was a realm-level setting. As of this\nfeature level, `email_address_visibility` is a user setting.\n" - }, - "client": { - "type": "string", - "description": "A Zulip \"client\" string, describing what Zulip client\nsent the message.\n" - }, - "content": { - "type": "string", - "description": "The content/body of the message.\nWhen `apply_markdown` is set, it will be in HTML format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "content_type": { - "type": "string", - "description": "The HTTP `content_type` for the message content. This\nwill be `text/html` or `text/x-markdown`, depending on\nwhether `apply_markdown` was set.\n\nSee the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.\n" - }, - "display_recipient": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "ID of the user.\n" - }, - "email": { - "type": "string", - "description": "Zulip API email of the user.\n" - }, - "full_name": { - "type": "string", - "description": "Full name of the user.\n" - }, - "is_mirror_dummy": { - "type": "boolean", - "description": "Whether the user is a mirror dummy.\n" - } - } - } - } - ], - "description": "Data on the recipient of the message;\neither the name of a channel or a dictionary containing basic data on\nthe users who received the message.\n" - }, - "edit_history": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "prev_content": { - "type": "string", - "description": "Only present if message's content was edited.\n\nThe content of the message immediately prior to this\nedit event.\n" - }, - "prev_rendered_content": { - "type": "string", - "description": "Only present if message's content was edited.\n\nThe rendered HTML representation of `prev_content`.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "prev_stream": { - "type": "integer", - "description": "Only present if message's channel was edited.\n\nThe channel ID of the message immediately prior to this\nedit event.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n" - }, - "prev_topic": { - "type": "string", - "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately prior to this\nedit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\nPreviously, this field was called `prev_subject`;\nclients are recommended to rename `prev_subject` to\n`prev_topic` if present for compatibility with\nolder Zulip servers.\n" - }, - "stream": { - "type": "integer", - "description": "Only present if message's channel was edited.\n\nThe ID of the channel containing the message\nimmediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" - }, - "timestamp": { - "type": "integer", - "description": "The UNIX timestamp for the edit.\n" - }, - "topic": { - "type": "string", - "description": "Only present if message's topic was edited.\n\nThe topic of the message immediately after this edit event.\n\n**Changes**: New in Zulip 5.0 (feature level 118).\n" - }, - "user_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user that made the edit.\n\nWill be `null` only for edit history\nevents predating March 2017.\n\nClients can display edit history events where this\nis `null` as modified by either the sender (for content\nedits) or an unknown user (for topic edits).\n" - } - }, - "required": ["user_id", "timestamp"] - }, - "description": "An array of objects, with each object documenting the\nchanges in a previous edit made to the message,\nordered chronologically from most recent to least recent\nedit.\n\nNot present if the message has never been edited or moved,\nor if [viewing message edit history][edit-history-access]\nis not allowed in the organization.\n\nEvery object will contain `user_id` and `timestamp`.\n\nThe other fields are optional, and will be present or not\ndepending on whether the channel, topic, and/or message\ncontent were modified in the edit event. For example, if\nonly the topic was edited, only `prev_topic` and `topic`\nwill be present in addition to `user_id` and `timestamp`.\n\n[edit-history-access]: /help/restrict-message-edit-history-access\n\n**Changes**: In Zulip 10.0 (feature level 284), removed the\n`prev_rendered_content_version` field as it is an internal\nserver implementation detail not used by any client.\n" - }, - "id": { - "type": "integer", - "description": "The unique message ID. Messages should always be\ndisplayed sorted by ID.\n" - }, - "is_me_message": { - "type": "boolean", - "description": "Whether the message is a [/me status message][status-messages]\n\n[status-messages]: /help/format-your-message-using-markdown#status-messages\n" - }, - "last_edit_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message's content was last edited, in\nUTC seconds.\n\nNot present if the message's content has never been edited.\n\nClients should use this field, rather than parsing the `edit_history`\narray, to display an indicator that the message has been edited.\n\n**Changes**: Prior to Zulip 10.0 (feature level 365), this was the\ntime when the message was last edited or moved.\n" - }, - "last_moved_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message was last moved to a different\nchannel or topic, in UTC seconds.\n\nNot present if the message has never been moved, or if the only topic\nmoves for the message are [resolving or unresolving](/help/resolve-a-topic)\nthe message's topic.\n\nClients should use this field, rather than parsing the `edit_history`\narray, to display an indicator that the message has been moved.\n\n**Changes**: New in Zulip 10.0 (feature level 365). Previously,\nparsing the `edit_history` array was required in order to correctly\ndisplay moved message indicators.\n" - }, - "reactions": { - "type": "array", - "description": "Data on any reactions to the message.\n", - "items": { - "$ref": "#/components/schemas/EmojiReaction" - } - }, - "recipient_id": { - "type": "integer", - "description": "A unique ID for the set of users receiving the\nmessage (either a channel or group of users). Useful primarily\nfor hashing.\n\n**Changes**: Before Zulip 10.0 (feature level 327), `recipient_id`\nwas the same across all incoming 1:1 direct messages. Now, each\nincoming message uniquely shares a `recipient_id` with outgoing\nmessages in the same conversation.\n" - }, - "sender_email": { - "type": "string", - "description": "The Zulip API email address of the message's sender.\n" - }, - "sender_full_name": { - "type": "string", - "description": "The full name of the message's sender.\n" - }, - "sender_id": { - "type": "integer", - "description": "The user ID of the message's sender.\n" - }, - "sender_realm_str": { - "type": "string", - "description": "A string identifier for the realm the sender is in. Unique only within\nthe context of a given Zulip server.\n\nE.g. on `example.zulip.com`, this will be `example`.\n" - }, - "stream_id": { - "type": "integer", - "description": "Only present for channel messages; the ID of the channel.\n" - }, - "subject": { - "type": "string", - "description": "The `topic` of the message. Currently always `\"\"` for direct messages,\nthough this could change if Zulip adds support for topics in direct\nmessage conversations.\n\nThe field name is a legacy holdover from when topics were\ncalled \"subjects\" and will eventually change.\n\nFor clients that don't support the `empty_topic_name` [client capability][client-capabilities],\nthe empty string value is replaced with the value of `realm_empty_topic_display_name`\nfound in the [POST /register](/api/register-queue) response, for channel messages.\n\n**Changes**: Before Zulip 10.0 (feature level 334), `empty_topic_name`\nclient capability didn't exist and empty string as the topic name for\nchannel messages wasn't allowed.\n\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n" - }, - "submessages": { - "type": "array", - "description": "Data used for certain experimental Zulip integrations.\n", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "msg_type": { - "type": "string", - "description": "The type of the message.\n" - }, - "content": { - "type": "string", - "description": "The new content of the submessage.\n" - }, - "message_id": { - "type": "integer", - "description": "The ID of the message to which the submessage has been added.\n" - }, - "sender_id": { - "type": "integer", - "description": "The ID of the user who sent the message.\n" - }, - "id": { - "type": "integer", - "description": "The ID of the submessage.\n" - } - } - } - }, - "timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message was sent,\nin UTC seconds.\n" - }, - "topic_links": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "properties": { - "text": { - "type": "string", - "description": "The original link text present in the topic.\n" - }, - "url": { - "type": "string", - "description": "The expanded target url which the link points to.\n" - } - } - }, - "description": "Data on any links to be included in the `topic`\nline (these are generated by [custom linkification\nfilters](/help/add-a-custom-linkifier) that match content in the\nmessage's topic.)\n\n**Changes**: This field contained a list of urls before\nZulip 4.0 (feature level 46).\n\nNew in Zulip 3.0 (feature level 1). Previously, this field was called\n`subject_links`; clients are recommended to rename `subject_links` to `topic_links`\nif present for compatibility with older Zulip servers.\n" - }, - "type": { - "type": "string", - "description": "The type of the message: `\"stream\"` or `\"private\"`.\n" - } - } - }, - "ModernPresenceFormat": { - "type": "object", - "description": "`{user_id}`: Presence data (modern format) for the user with\nthe specified ID.\n", - "additionalProperties": false, - "properties": { - "active_timestamp": { - "type": "integer", - "description": "The UNIX timestamp of the last time a client connected\nto Zulip reported that the user was actually present\n(e.g. via focusing a browser window or interacting\nwith a computer running the desktop app).\n\nClients should display users with a current\n`active_timestamp` as fully present.\n" - }, - "idle_timestamp": { - "type": "integer", - "description": "The UNIX timestamp of the last time the user had a\nclient connected to Zulip, including idle clients\nwhere the user hasn't interacted with the system\nrecently.\n\nThe Zulip server has no way of distinguishing whether\nan idle web app user is at their computer, but hasn't\ninteracted with the Zulip tab recently, or simply left\ntheir desktop computer on when they left.\n\nThus, clients should display users with a current\n`idle_timestamp` but no current `active_timestamp` as\npotentially present.\n" - } - } - }, - "LegacyPresenceFormat": { - "type": "object", - "description": "`{client_name}` or `\"aggregated\"`: Object containing the details of the user's\npresence.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will always\ncontain two keys, `\"website\"` and `\"aggregated\"`, with identical data. The\nserver no longer stores which client submitted presence updates.\n\nPreviously, the `{client_name}` keys for these objects were the names of the\ndifferent clients where the user was logged in, for example `website` or\n`ZulipDesktop`.\n", - "additionalProperties": false, - "properties": { - "client": { - "type": "string", - "description": "The client's platform name.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), this will\nalways be `\"website\"` as the server no longer stores which client\nsubmitted presence data.\n" - }, - "status": { - "type": "string", - "enum": ["idle", "active"], - "description": "The status of the user on this client. Will be either `\"idle\"`\nor `\"active\"`.\n" - }, - "timestamp": { - "type": "integer", - "description": "The UNIX timestamp of when this client sent the user's presence\nto the server with the precision of a second.\n" - }, - "pushable": { - "type": "boolean", - "description": "Whether the client is capable of showing mobile/push notifications\nto the user.\n\nNot present in objects with the `\"aggregated\"` key.\n\n**Changes**: Starting with Zulip 7.0 (feature level 178), always\n`false` when present as the server no longer stores which client\nsubmitted presence data.\n" - } - } - }, - "UserStatus": { - "type": "object", - "additionalProperties": false, - "properties": { - "away": { - "type": "boolean", - "deprecated": true, - "description": "If present, the user has marked themself \"away\".\n\n**Changes**: Deprecated in Zulip 6.0 (feature level 148);\nstarting with that feature level, `away` is a legacy way to\naccess the user's `presence_enabled` setting, with\n`away = !presence_enabled`. To be removed in a future release.\n" - }, - "status_text": { - "type": "string", - "description": "If present, the text content of the user's status message.\n" - }, - "emoji_name": { - "type": "string", - "description": "If present, the name for the emoji to associate with the user's status.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - }, - "emoji_code": { - "type": "string", - "description": "If present, a unique identifier, defining the specific emoji codepoint\nrequested, within the namespace of the `reaction_type`.\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - }, - "reaction_type": { - "type": "string", - "enum": ["unicode_emoji", "realm_emoji", "zulip_extra_emoji"], - "description": "If present, a string indicating the type of emoji. Each emoji\n`reaction_type` has an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" - } - } - }, - "Draft": { - "type": "object", - "description": "A dictionary for representing a message draft.\n", - "properties": { - "id": { - "type": "integer", - "description": "The unique ID of the draft. It will only used whenever the drafts are\nfetched. This field should not be specified when the draft is being\ncreated or edited.\n" - }, - "type": { - "type": "string", - "description": "The type of the draft. Either unaddressed (empty string), `\"stream\"`,\nor `\"private\"` (for one-on-one and group direct messages).\n", - "enum": ["", "stream", "private"] - }, - "to": { - "type": "array", - "description": "An array of the tentative target audience IDs. For channel\nmessages, this should contain exactly 1 ID, the ID of the\ntarget channel. For direct messages, this should be an array\nof target user IDs. For unaddressed drafts, this is ignored,\nand clients should send an empty array.\n", - "items": { - "type": "integer" - } - }, - "topic": { - "type": "string", - "description": "For channel message drafts, the tentative topic name. For direct\nor unaddressed messages, this will be ignored and should ideally\nbe the empty string. Should not contain null bytes.\n" - }, - "content": { - "type": "string", - "description": "The body of the draft. Should not contain null bytes.\n" - }, - "timestamp": { - "type": "integer", - "description": "A Unix timestamp (seconds only) representing when the draft was\nlast edited. When creating a draft, this key need not be present\nand it will be filled in automatically by the server.\n", - "example": 1595479019 - } - }, - "additionalProperties": false, - "required": ["type", "to", "topic", "content"] - }, - "NavigationView": { - "type": "object", - "description": "Represents a user's personal configuration for a specific\nnavigation view (displayed most visibly at the top of the web\napplication's left sidebar).\n\nNavigation views can be either an override to the default\nbehavior of a built-in view, or a custom view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n", - "additionalProperties": false, - "required": ["fragment", "is_pinned"], - "properties": { - "fragment": { - "type": "string", - "description": "A unique identifier for the view, used to determine navigation\nbehavior when clicked.\n\nClients should use this value to navigate to the corresponding URL hash.\n", - "example": "narrow/is/alerted" - }, - "is_pinned": { - "type": "boolean", - "description": "Determines whether the view appears directly in the sidebar or\nis hidden in the \"More Views\" menu.\n\n- `true` - Pinned and visible in the sidebar.\n- `false` - Hidden and accessible via the \"More Views\" menu.\n", - "example": true - }, - "name": { - "type": "string", - "nullable": true, - "description": "The user-facing name for custom navigation views. Omit this\nfield for built-in views.\n", - "example": "Alert Words" - } - } - }, - "SavedSnippet": { - "type": "object", - "description": "Object containing the details of the saved snippet.\n", - "additionalProperties": false, - "properties": { - "id": { - "type": "integer", - "description": "The unique ID of the saved snippet.\n" - }, - "title": { - "type": "string", - "description": "The title of the saved snippet.\n" - }, - "content": { - "type": "string", - "description": "The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nClients should insert this content into a message when using\na saved snippet.\n" - }, - "date_created": { - "type": "integer", - "description": "The UNIX timestamp for when the saved snippet was created, in\nUTC seconds.\n" - } - } - }, - "ScheduledMessageBase": { - "type": "object", - "description": "Object containing details of the scheduled message.\n", - "properties": { - "scheduled_message_id": { - "type": "integer", - "description": "The unique ID of the scheduled message, which can be used to\nmodify or delete the scheduled message.\n\nThis is different from the unique ID that the message will have\nafter it is sent.\n" - }, - "type": { - "type": "string", - "description": "The type of the scheduled message. Either `\"stream\"` or `\"private\"`.\n", - "enum": ["stream", "private"] - }, - "to": { - "oneOf": [ - { - "type": "integer" - }, - { - "type": "array", - "items": { - "type": "integer" - } - } - ], - "description": "The scheduled message's tentative target audience.\n\nFor channel messages, it will be the unique ID of the target\nchannel. For direct messages, it will be an array with the\ntarget users' IDs.\n" - }, - "topic": { - "type": "string", - "description": "Only present if `type` is `\"stream\"`.\n\nThe topic for the channel message.\n" - }, - "content": { - "type": "string", - "description": "The content/body of the scheduled message, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "rendered_content": { - "type": "string", - "description": "The content/body of the scheduled message rendered in HTML.\n" - }, - "scheduled_delivery_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message will be sent\nby the server, in UTC seconds.\n", - "example": 1595479019 - }, - "failed": { - "type": "boolean", - "description": "Whether the server has tried to send the scheduled message\nand it failed to successfully send.\n\nClients that support unscheduling and editing scheduled messages\nshould display scheduled messages with `\"failed\": true` with an\nindicator that the server failed to send the message at the\nscheduled time, so that the user is aware of the failure and can\nget the content of the scheduled message.\n\n**Changes**: New in Zulip 7.0 (feature level 181).\n" - } - }, - "additionalProperties": false, - "required": [ - "scheduled_message_id", - "type", - "to", - "content", - "rendered_content", - "scheduled_delivery_timestamp", - "failed" - ] - }, - "ScheduledMessage": { - "allOf": [ - { - "$ref": "#/components/schemas/ScheduledMessageBase" - }, - { - "additionalProperties": false, - "properties": { - "scheduled_message_id": {}, - "type": {}, - "to": {}, - "topic": {}, - "content": {}, - "rendered_content": {}, - "scheduled_delivery_timestamp": {}, - "failed": {} - } - } - ] - }, - "Reminder": { - "type": "object", - "additionalProperties": false, - "description": "Object containing details of the scheduled message.\n", - "properties": { - "reminder_id": { - "type": "integer", - "description": "The unique ID of the reminder, which can be used to\ndelete the reminder.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n" - }, - "type": { - "type": "string", - "description": "The type of the reminder. Always set to `\"private\"`.\n", - "enum": ["private"] - }, - "to": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "Contains the ID of the user who scheduled the reminder,\nand to which the reminder will be sent.\n" - }, - "content": { - "type": "string", - "description": "The content/body of the reminder, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - }, - "rendered_content": { - "type": "string", - "description": "The content/body of the reminder rendered in HTML.\n" - }, - "scheduled_delivery_timestamp": { - "type": "integer", - "description": "The UNIX timestamp for when the message will be sent\nby the server, in UTC seconds.\n", - "example": 1595479019 - }, - "failed": { - "type": "boolean", - "description": "Whether the server has tried to send the reminder\nand it failed to successfully send.\n\nClients that support unscheduling reminders\nshould display scheduled messages with `\"failed\": true` with an\nindicator that the server failed to send the message at the\nscheduled time, so that the user is aware of the failure and can\nget the content of the scheduled message.\n" - }, - "reminder_target_message_id": { - "type": "integer", - "description": "The ID of the message that the reminder is created for.\n" - } - }, - "required": [ - "reminder_id", - "type", - "to", - "content", - "rendered_content", - "scheduled_delivery_timestamp", - "failed", - "reminder_target_message_id" - ] - }, - "GroupPermissionSetting": { - "description": "Configuration for a group permission setting specifying the groups\nto which the setting can be set to and the default values for the\nsetting.\n\n**Changes**: Removed `allow_owners_group` field in Zulip 10.0 (feature level 326), as we now\nsupport anonymous user groups. Previously, the `role:owners` system group was\nnot offered when `allow_owners_group` was false.\n\nRemoved unnecessary `id_field_name` field in Zulip 10.0 (feature level 326). Previously,\nthis always had the value of `\"{setting_name}_id\"`; it was an internal implementation\ndetail of the server not intended to be included in the API.\n", - "additionalProperties": false, - "type": "object", - "properties": { - "require_system_group": { - "type": "boolean", - "description": "Whether the setting can only be set to a system user group.\n" - }, - "allow_internet_group": { - "type": "boolean", - "description": "Whether the setting can be set to `role:internet` system group.\n" - }, - "allow_nobody_group": { - "type": "boolean", - "description": "Whether the setting can be set to `role:nobody` system group.\n" - }, - "allow_everyone_group": { - "type": "boolean", - "description": "Whether the setting can be set to `role:everyone` system group.\n\nIf false, guest users cannot exercise this permission even if they are part of\nthe [group-setting value](/api/group-setting-values) for this setting.\n" - }, - "default_group_name": { - "type": "string", - "description": "Name of the default group for the setting.\n" - }, - "default_for_system_groups": { - "type": "string", - "nullable": true, - "description": "Name of the default group for the setting for system groups.\n\nThis is non-null only for group-level settings.\n" - }, - "allowed_system_groups": { - "type": "array", - "description": "An array of names of system groups to which the setting can\nbe set to.\n\nIf the list is empty, the setting can be set to system groups\nbased on the other boolean fields.\n\n**Changes**: New in Zulip 8.0 (feature level 225).\n", - "items": { - "type": "string" - } - } - } - }, - "User": { - "allOf": [ - { - "$ref": "#/components/schemas/UserBase" - }, - { - "additionalProperties": false, - "properties": { - "user_id": {}, - "delivery_email": { - "nullable": true - }, - "email": {}, - "full_name": {}, - "date_joined": {}, - "is_active": {}, - "is_owner": {}, - "is_admin": {}, - "is_guest": {}, - "is_bot": {}, - "bot_type": { - "nullable": true - }, - "bot_owner_id": { - "nullable": true - }, - "role": {}, - "timezone": {}, - "avatar_url": { - "nullable": true - }, - "avatar_version": {}, - "profile_data": {} - } - } - ] - }, - "UserBase": { - "type": "object", - "description": "A dictionary containing basic data on a given Zulip user.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was\nreplaced by the `can_manage_billing_group` realm setting.\n", - "properties": { - "user_id": { - "type": "integer", - "description": "The unique ID of the user.\n" - }, - "delivery_email": { - "type": "string", - "nullable": true, - "description": "The user's real email address. This value will be `null` if you cannot\naccess user's real email address. For bot users, this field is always\nset to the real email of the bot, because bot users always have\n`email_address_visibility` set to everyone.\n\n**Changes**: Prior to Zulip 7.0 (feature level 163), this field was\npresent only when `email_address_visibility` was restricted and you had\naccess to the user's real email. As of this feature level, this field\nis always present, including the case when `email_address_visibility`\nis set to everyone (and therefore not restricted).\n" - }, - "email": { - "type": "string", - "description": "The Zulip API email address of the user or bot.\n\nIf you do not have permission to view the email address of the target user,\nthis will be a fake email address that is usable for the Zulip API but nothing else.\n" - }, - "full_name": { - "type": "string", - "description": "Full name of the user or bot, used for all display purposes.\n" - }, - "date_joined": { - "type": "string", - "description": "The time the user account was created.\n" - }, - "is_active": { - "type": "boolean", - "description": "A boolean specifying whether the user account has been deactivated.\n" - }, - "is_owner": { - "type": "boolean", - "description": "A boolean specifying whether the user is an organization owner.\nIf true, `is_admin` will also be true.\n\n**Changes**: New in Zulip 3.0 (feature level 8).\n" - }, - "is_admin": { - "type": "boolean", - "description": "A boolean specifying whether the user is an organization administrator.\n" - }, - "is_guest": { - "type": "boolean", - "description": "A boolean specifying whether the user is a guest user.\n" - }, - "is_bot": { - "type": "boolean", - "description": "A boolean specifying whether the user is a bot or full account.\n" - }, - "bot_type": { - "type": "integer", - "nullable": true, - "description": "An integer describing the type of bot:\n\n- `null` if the user isn't a bot.\n- `1` for a `Generic` bot.\n- `2` for an `Incoming webhook` bot.\n- `3` for an `Outgoing webhook` bot.\n- `4` for an `Embedded` bot.\n" - }, - "bot_owner_id": { - "type": "integer", - "nullable": true, - "description": "If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`\nis the user ID of the bot's owner (usually, whoever created the bot).\n\nWill be `null` for legacy bots that do not have an owner.\n\n**Changes**: New in Zulip 3.0 (feature level 1). In previous\nversions, there was a `bot_owner` field containing the email\naddress of the bot's owner.\n" - }, - "role": { - "type": "integer", - "enum": [100, 200, 300, 400, 600], - "description": "[Organization-level role](/api/roles-and-permissions) of the user.\nPossible values are:\n\n- 100 = Organization owner\n- 200 = Organization administrator\n- 300 = Organization moderator\n- 400 = Member\n- 600 = Guest\n\n**Changes**: New in Zulip 4.0 (feature level 59).\n" - }, - "timezone": { - "type": "string", - "description": "The IANA identifier of the user's [profile time zone](/help/change-your-timezone),\nwhich is used primarily to display the user's local time to other users.\n" - }, - "avatar_url": { - "type": "string", - "nullable": true, - "description": "URL for the user's avatar.\n\nWill be `null` if the `client_gravatar`\nquery parameter was set to `true`, the current user has access to\nthis user's real email address, and this user's avatar is hosted by\nthe Gravatar provider (i.e. this user has never uploaded an avatar).\n\n**Changes**: Before Zulip 7.0 (feature level 163), access to a\nuser's real email address was a realm-level setting. As of this\nfeature level, `email_address_visibility` is a user setting.\n\nIn Zulip 3.0 (feature level 18), if the client has the\n`user_avatar_url_field_optional` capability, this will be missing at\nthe server's sole discretion.\n" - }, - "avatar_version": { - "type": "integer", - "description": "Version for the user's avatar. Used for cache-busting requests\nfor the user's avatar. Clients generally shouldn't need to use this;\nmost avatar URLs sent by Zulip will already end with `?v={avatar_version}`.\n" - }, - "profile_data": { - "$ref": "#/components/schemas/profile_data" - } - } - }, - "profile_data": { - "type": "object", - "description": "Only present if `is_bot` is false; bots can't have custom profile fields.\n\nA dictionary containing custom profile field data for the user. Each entry\nmaps the integer ID of a custom profile field in the organization to a\ndictionary containing the user's data for that field. Generally the data\nincludes just a single `value` key; for those custom profile fields\nsupporting Markdown, a `rendered_value` key will also be present.\n", - "additionalProperties": { - "type": "object", - "additionalProperties": false, - "description": "`{id}`: Object with data about what value the user filled in the custom\nprofile field with that ID.\n", - "properties": { - "value": { - "type": "string", - "description": "User's personal value for this custom profile field.\n" - }, - "rendered_value": { - "type": "string", - "description": "The `value` rendered in HTML. Will only be present for\ncustom profile field types that support Markdown rendering.\n\nThis user-generated HTML content should be rendered\nusing the same CSS and client-side security protections\nas are used for message content.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" - } - } - } - }, - "ChannelFolder": { - "type": "object", - "additionalProperties": false, - "description": "Object containing the channel folder's attributes.\n", - "properties": { - "id": { - "type": "integer", - "description": "The unique ID of the channel folder.\n" - }, - "name": { - "type": "string", - "description": "The name of the channel folder.\n" - }, - "order": { - "type": "integer", - "description": "This value determines in which order the channel folder should be\ndisplayed in the UI. The value is 0 indexed, and a channel folder with\na lower value should be displayed before channel folders with higher\nvalues.\n\n**Changes**: New in Zulip 11.0 (feature level 414).\n" - }, - "date_created": { - "type": "integer", - "nullable": true, - "description": "The UNIX timestamp for when the channel folder was created,\nin UTC seconds.\n" - }, - "creator_id": { - "type": "integer", - "nullable": true, - "description": "The ID of the user who created the channel folder.\n" - }, - "description": { - "type": "string", - "description": "The description of the channel folder. Can be an empty string.\n\nSee [Markdown message formatting](/api/message-formatting) for details\non Zulip's HTML format.\n" - }, - "rendered_description": { - "type": "string", - "description": "The description of the channel folder rendered as HTML, intended to be\nused for UI that displays the channel folder description.\n\nClients should use the standard Zulip rendered_markdown CSS when\ndisplaying this content so that emoji, LaTeX, and other syntax work\ncorrectly. And any client-side security logic for user-generated\nmessage content should be applied when displaying this HTML as though\nit were the body of a Zulip message.\n" - }, - "is_archived": { - "type": "boolean", - "description": "Whether the channel folder is archived or not.\n" - } - } - }, - "JsonResponseBase": { - "type": "object", - "properties": { - "result": { - "type": "string" - } - } - }, - "JsonSuccess": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {} - }, - "example": { - "msg": "", - "result": "success" - } - } - ] - }, - "JsonSuccessBase": { - "description": "**Changes**: As of Zulip 7.0 (feature level 167), if any\nparameters sent in the request are not supported by this\nendpoint, a successful JSON response will include an\n[`ignored_parameters_unsupported`][ignored_params] array.\n\nA typical successful JSON response may look like:\n\n[ignored_params]: /api/rest-error-handling#ignored-parameters\n", - "allOf": [ - { - "$ref": "#/components/schemas/JsonResponseBase" - }, - { - "required": ["result", "msg"], - "properties": { - "result": { - "enum": ["success"] - }, - "msg": { - "type": "string" - }, - "ignored_parameters_unsupported": { - "$ref": "#/components/schemas/IgnoredParametersUnsupported" - } - } - } - ] - }, - "IgnoredParametersSuccess": { - "allOf": [ - { - "$ref": "#/components/schemas/IgnoredParametersBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {} - } - } - ], - "description": "**Changes**: The [`ignored_parameters_unsupported`][ignored_params]\narray was added as a possible return value for all REST API endpoint\nJSON success responses in Zulip 7.0 (feature level 167).\n\nPreviously, it was added to\n[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings)\nin Zulip 5.0 (feature level 111) and to\n[`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults)\nin Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0\n(feature level 78) as a return value for the\n[`PATCH /settings`](/api/update-settings) endpoint.\n\nA typical successful JSON response with ignored parameters may look like:\n\n[ignored_params]: /api/rest-error-handling#ignored-parameters\n", - "example": { - "ignored_parameters_unsupported": [ - "invalid_param_1", - "invalid_param_2" - ], - "msg": "", - "result": "success" - } - }, - "IgnoredParametersBase": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonResponseBase" - }, - { - "required": ["result", "msg"], - "properties": { - "result": { - "enum": ["success"] - }, - "msg": { - "type": "string" - }, - "ignored_parameters_unsupported": { - "$ref": "#/components/schemas/IgnoredParametersUnsupported" - } - } - } - ] - }, - "ApiKeyResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonSuccessBase" - }, - { - "required": ["api_key", "email"], - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "ignored_parameters_unsupported": {}, - "api_key": { - "type": "string", - "description": "The API key that can be used to authenticate as the requested user.\n" - }, - "email": { - "type": "string", - "description": "The email address of the user who owns the API key.\n" - }, - "user_id": { - "type": "integer", - "description": "The unique ID of the user who owns the API key.\n\n**Changes**: New in Zulip 7.0 (feature level 171).\n" - } - }, - "example": { - "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv", - "email": "iago@zulip.com", - "msg": "", - "result": "success", - "user_id": 5 - } - } - ] - }, - "CodedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {} - } - } - ] - }, - "CodedErrorBase": { - "allOf": [ - { - "$ref": "#/components/schemas/JsonResponseBase" - }, - { - "required": ["result", "msg", "code"], - "properties": { - "result": { - "enum": ["error"] - }, - "msg": { - "type": "string" - }, - "code": { - "type": "string", - "description": "A string that identifies the error.\n" - } - } - } - ] - }, - "BadEventQueueIdError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "queue_id": { - "type": "string", - "description": "The string that identifies the invalid event queue.\n" - } - }, - "example": { - "code": "BAD_EVENT_QUEUE_ID", - "msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8", - "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", - "result": "error" - } - } - ] - }, - "InvalidMessageError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {} - }, - "example": { - "msg": "Invalid message(s)", - "code": "BAD_REQUEST", - "result": "error" - } - } - ] - }, - "InvalidChannelError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {} - }, - "example": { - "msg": "Invalid channel ID", - "code": "BAD_REQUEST", - "result": "error" - } - } - ] - }, - "NonExistingChannelNameError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "stream": { - "type": "string", - "description": "The name of the channel that could not be found.\n" - } - }, - "example": { - "code": "STREAM_DOES_NOT_EXIST", - "msg": "Channel 'nonexistent' does not exist", - "result": "error", - "stream": "nonexistent" - } - } - ] - }, - "NonExistingChannelIdError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "stream_id": { - "type": "integer", - "description": "The channel ID that could not be found.\n" - } - }, - "example": { - "code": "STREAM_DOES_NOT_EXIST", - "msg": "Channel with ID '9' does not exist", - "result": "error", - "stream_id": 9 - } - } - ] - }, - "InvalidApiKeyError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "INVALID_API_KEY", - "msg": "Invalid API key", - "result": "error" - }, - "description": "### Invalid API key\n\nA typical failed JSON response for when the API key is invalid.\n" - } - ] - }, - "InvitationFailedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "errors": { - "type": "array", - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "boolean" - } - ] - } - }, - "description": "An array of arrays of length 3, where each inner array consists of (a) an email\naddress that was skipped while sending invitations, (b) the corresponding error\nmessage, and (c) a boolean which is `true` when the email address already uses Zulip\nand the corresponding user is deactivated in the organization.\n" - }, - "sent_invitations": { - "description": "A boolean specifying whether any invitations were sent.\n", - "type": "boolean" - }, - "daily_limit_reached": { - "type": "boolean", - "description": "A boolean specifying whether the limit on the number of invitations that can\nbe sent in the organization in a day has been reached.\n" - }, - "license_limit_reached": { - "type": "boolean", - "description": "A boolean specifying whether the organization have enough unused Zulip licenses\nto invite specified number of users.\n" - } - } - } - ] - }, - "MissingArgumentError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "description": "### Missing request parameter\n\nA typical failed JSON response for when a required request parameter\nis not supplied.\n\nThe value of `var_name` contains information about the missing parameter.\n", - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "var_name": { - "type": "string", - "description": "It contains the information about the missing parameter.\n" - } - }, - "example": { - "code": "REQUEST_VARIABLE_MISSING", - "msg": "Missing 'content' argument", - "result": "error", - "var_name": "content" - } - } - ] - }, - "IncompatibleParametersError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "description": "### Incompatible request parameters\n\nA typical failed JSON response for when two or more, optional\nparameters are supplied that are incompatible with each other.\n\nThe value of `parameters` in the response is string containing\nthe parameters, separated by commas, that are incompatible.\n", - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "parameters": { - "type": "string", - "description": "A string containing the parameters, separated by commas,\nthat are incompatible.\n" - } - }, - "example": { - "code": "BAD_REQUEST", - "msg": "Unsupported parameter combination: object_id, object_name", - "result": "error", - "parameters": "object_id, object_name" - } - } - ] - }, - "UserNotAuthorizedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "BAD_REQUEST", - "msg": "User not authorized for this query", - "result": "error" - }, - "description": "### User not authorized for query\n\nA typical failed JSON response for when the user is not authorized for\na query.\n" - } - ] - }, - "UserDeactivatedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "USER_DEACTIVATED", - "msg": "Account is deactivated", - "result": "error" - }, - "description": "### User account deactivated\n\nA typical failed json response for when user's account is deactivated.\n\n**Changes**: As of Zulip 5.0 (feature level 76), these errors use the\nHTTP 401 status code. Before this feature level, they used the HTTP 403\nstatus code.\n" - } - ] - }, - "RateLimitedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedErrorBase" - }, - { - "additionalProperties": false, - "description": "### Rate limit exceeded\n\nA typical failed JSON response for when a rate limit is exceeded.\nZulip sets a few [HTTP response headers][rate-limit-headers]\nto help with preventing rate limit errors.\n\nThe value of `retry-after` in the response indicates how many\nseconds the client must wait before making additional requests.\n\n**Changes**: Before Zulip 4.0 (feature level 36), the `code` key\nwas not present in rate limit errors.\n\n[rate-limit-headers]: /api/http-headers#rate-limiting-response-headers\n", - "properties": { - "result": {}, - "msg": {}, - "code": {}, - "retry-after": { - "type": "integer", - "description": "How many seconds the client must wait before making\nadditional requests.\n" - } - }, - "example": { - "code": "RATE_LIMIT_HIT", - "msg": "API usage exceeded rate limit", - "result": "error", - "retry-after": 28.706807374954224 - } - } - ] - }, - "RealmDeactivatedError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "REALM_DEACTIVATED", - "msg": "This organization is deactivated", - "result": "error" - }, - "description": "### Realm deactivated\n\nA typical failed json response for when user's organization is deactivated.\n\n**Changes**: As of Zulip 5.0 (feature level 76), these errors use the\nHTTP 401 status code. Before this feature level, they used the HTTP 403\nstatus code.\n" - } - ] - }, - "InvalidPushDeviceTokenError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "INVALID_PUSH_DEVICE_TOKEN", - "msg": "Device not recognized", - "result": "error" - }, - "description": "## Invalid push device token\n\nA typical failed JSON response for when the push device token is not\nrecognized by the Zulip server:\n" - } - ] - }, - "InvalidRemotePushDeviceTokenError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "INVALID_REMOTE_PUSH_DEVICE_TOKEN", - "msg": "Device not recognized by the push bouncer", - "result": "error" - }, - "description": "## Invalid push device token\n\nA typical failed JSON response for when the push device token is not recognized\nby the push notification bouncer:\n" - } - ] - }, - "NoActivePushDeviceError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "NO_ACTIVE_PUSH_DEVICE", - "msg": "No active registered push device", - "result": "error" - }, - "description": "## No active push device\n\nA typical failed JSON response for when no registered device is available\nfor the user (and `push_account_id`) to receive a push notification.\n" - } - ] - }, - "FailedToConnectBouncerError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "FAILED_TO_CONNECT_BOUNCER", - "msg": "Network error while connecting to Zulip push notification service.", - "result": "error" - }, - "description": "## Failed to connect bouncer\n\nA typical failed JSON response for when a network error occurs\nwhile the server attempts to connect to the bouncer server.\n" - } - ] - }, - "InternalBouncerServerError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "INTERNAL_SERVER_ERROR_ON_BOUNCER", - "msg": "Internal server error on Zulip push notification service, retry later.", - "result": "error" - }, - "description": "## Internal bouncer server error\n\nA typical failed JSON response for when a 5xx error occurs on the bouncer server.\n" - } - ] - }, - "PushNotificationAdminActionRequiredError": { - "allOf": [ - { - "$ref": "#/components/schemas/CodedError" - }, - { - "example": { - "code": "ADMIN_ACTION_REQUIRED", - "msg": "Push notification configuration issue on server, contact the server administrator or retry later.", - "result": "error" - }, - "description": "## Admin action required\n\nA typical failed JSON response for when there is a push notification\nconfiguration issue on the server, such as invalid credentials,\nan expired plan, or an unregistered organization. Admin action is required.\n" - } - ] - }, - "Event_types": { - "description": "A JSON-encoded array indicating which types of events you're interested\nin. Values that you might find useful include:\n\n- **message** (messages)\n- **subscription** (changes in your subscriptions)\n- **realm_user** (changes to users in the organization and\n their properties, such as their name).\n\nIf you do not specify this parameter, you will receive all\nevents, and have to filter out the events not relevant to\nyour client in your client code. For most applications, one\nis only interested in messages, so one specifies:\n`\"event_types\": [\"message\"]`\n\nEvent types not supported by the server are ignored, in order to simplify\nthe implementation of client apps that support multiple server versions.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": ["message"] - }, - "Narrow": { - "description": "A JSON-encoded array of arrays of length 2 indicating the\n[narrow filter(s)](/api/construct-narrow) for which you'd\nlike to receive events for.\n\nFor example, to receive events for direct messages (including\ngroup direct messages) received by the user, one can use\n`\"narrow\": [[\"is\", \"dm\"]]`.\n\nUnlike the API for [fetching messages](/api/get-messages),\nthis narrow parameter is simply a filter on messages that the\nuser receives through their channel subscriptions (or because\nthey are a recipient of a direct message).\n\nThis means that a client that requests a `narrow` filter of\n`[[\"channel\", \"Denmark\"]]` will receive events for new messages\nsent to that channel while the user is subscribed to that\nchannel. The client will not receive any message events at all\nif the user is not subscribed to `\"Denmark\"`.\n\nNewly created bot users are not usually subscribed to any\nchannels, so bots using this API need to be\n[subscribed](/api/subscribe) to any channels whose messages\nyou'd like them to process using this endpoint.\n\nSee the `all_public_streams` parameter for how to process all\npublic channel messages in an organization.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n", - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string" - } - }, - "default": [], - "example": [["channel", "Denmark"]] - }, - "AllPublicChannels": { - "description": "Whether you would like to request message events from all public\nchannels. Useful for workflow bots that you'd like to see all new messages\nsent to public channels. (You can also subscribe the user to private channels).\n", - "type": "boolean", - "default": false, - "example": true - }, - "RequiredContent": { - "description": "The content of the message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n", - "type": "string", - "example": "Hello" - }, - "OptionalContent": { - "description": "The updated content of the target message.\n\nClients should use the `max_message_length` returned by the\n[`POST /register`](/api/register-queue) endpoint to determine\nthe maximum message size.\n\nNote that a message's content and channel cannot be changed at the\nsame time, so sending both `content` and `stream_id` parameters will\nthrow an error.\n", - "type": "string", - "example": "Hello" - }, - "HistoryPublicToSubscribers": { - "description": "Whether the channel's message history should be available to\nnewly subscribed members, or users can only access messages\nthey actually received while subscribed to the channel.\n\nCorresponds to the shared history option for\n[private channels](/help/channel-permissions#private-channels).\n", - "type": "boolean", - "example": false - }, - "Principals": { - "description": "A list of user IDs (preferred) or Zulip API email\naddresses of the users to be subscribed to or unsubscribed\nfrom the channels specified in the `subscriptions` parameter. If\nnot provided, then the requesting user/bot is subscribed.\n\n**Changes**: The integer format is new in Zulip 3.0 (feature level 9).\n", - "oneOf": [ - { - "type": "array", - "items": { - "type": "string" - } - }, - { - "type": "array", - "items": { - "type": "integer" - } - } - ], - "example": ["ZOE@zulip.com"] - }, - "ReactionType": { - "description": "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nIf an API client is adding/removing a vote on an existing reaction,\nit should pass this parameter using the value the server provided\nfor the existing reaction for specificity. Supported values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: In Zulip 3.0 (feature level 2), this parameter became\noptional for [custom emoji](/help/custom-emoji);\npreviously, this endpoint assumed `unicode_emoji` if this\nparameter was not specified.\n", - "type": "string", - "example": "unicode_emoji" - }, - "EmojiCode": { - "description": "A unique identifier, defining the specific emoji codepoint requested,\nwithin the namespace of the `reaction_type`.\n\nFor most API clients, you won't need this, but it's important\nfor Zulip apps to handle rare corner cases when\nadding/removing votes on an emoji reaction added previously by\nanother user.\n\nIf the existing reaction was added when the Zulip server was\nusing a previous version of the emoji data mapping between\nUnicode codepoints and human-readable names, sending the\n`emoji_code` in the data for the original reaction allows the\nZulip server to correctly interpret your upvote as an upvote\nrather than a reaction with a \"different\" emoji.\n", - "type": "string", - "example": "1f419" - }, - "MessageRetentionDays": { - "description": "Number of days that messages sent to this channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). Two special string format\nvalues are supported:\n\n- `\"realm_default\"`: Return to the organization-level setting.\n- `\"unlimited\"`: Retain messages forever.\n\n**Changes**: Prior to Zulip 5.0 (feature level 91), retaining\nmessages forever was encoded using `\"forever\"` instead of\n`\"unlimited\"`.\n\nNew in Zulip 3.0 (feature level 17).\n", - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ], - "example": "20" - }, - "TopicsPolicy": { - "type": "string", - "enum": [ - "inherit", - "allow_empty_topic", - "disable_empty_topic", - "empty_topic_only" - ], - "example": "inherit", - "description": "Whether [named topics](/help/introduction-to-topics) and the empty\ntopic (i.e., [\"general chat\" topic](/help/general-chat-topic))\nare enabled in this channel.\n\n- `\"inherit\"`: Messages can be sent to named topics in this channel,\n and the [organization-level `realm_topics_policy`][realm-topics-policy]\n is used for whether messages can be sent to the empty topic in this\n channel.\n- `\"allow_empty_topic\"`: Messages can be sent to both named topics and\n the empty topic in this channel.\n- `\"disable_empty_topic\"`: Messages can be sent to named topics in this\n channel, but the empty topic is disabled.\n- `\"empty_topic_only\"`: Messages can be sent to the empty topic in this\n channel, but named topics are disabled. See [\"general chat\"\n channels](/help/general-chat-channels).\n\nThe `\"empty_topic_only\"` policy can only be set if all existing messages\nin the channel are already in the empty topic.\n\nWhen creating a new channel, if the `topics_policy` is not specified, the\n`\"inherit\"` option will be set.\n\n**Changes**: In Zulip 11.0 (feature level 404), the `\"empty_topic_only\"`\noption was added.\n\nNew in Zulip 11.0 (feature level 392).\n\n[realm-topics-policy]: /help/require-topics#set-the-default-general-chat-topic-configuration\n" - }, - "SendNewSubscriptionMessages": { - "description": "Whether any other users newly subscribed via this request should be\nsent a direct message, from Notification Bot, notifying them about their\nnew subscription.\n\nNo direct messages are sent for any channels that are created as part of\nthis request, regardless of the value of this parameter.\n\nThe server will never send direct messages when the total number of users\nwho were subscribed to channels in this request was more than the value\nof `max_bulk_new_subscription_messages`, which is available in the [`POST\n/register`](/api/register-queue) response.\n\n**Changes**: Before Zulip 11.0 (feature level 397), new subscribers\nwere always sent a Notification Bot direct message, which was unduly\nexpensive when bulk-subscribing thousands of users to a channel.\n", - "type": "boolean", - "default": true, - "example": true - }, - "ChannelCanAddSubscribersGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to add subscribers to this channel.\n\nUsers who can administer the channel or have similar realm-level\npermissions can add subscribers to a public channel regardless\nof the value of this setting.\n\nUsers in this group need not be subscribed to a private channel to\nadd subscribers to it.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 342). Previously, there was no\nchannel-level setting for this permission.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanRemoveSubscribersGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to remove subscribers from this channel.\n\nOrganization administrators can unsubscribe others from a channel as though\nthey were in this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349), channel administrators\ncould not unsubscribe other users if they were not an organization\nadministrator or part of `can_remove_subscribers_group`. Realm administrators\nwere not allowed to unsubscribe other users from a private channel if they\nwere not subscribed to that channel.\n\nPrior to Zulip 10.0 (feature level 320), this value was always the integer\nID of a system group.\n\nBefore Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`\nsetting was named `can_remove_subscribers_group_id`.\n\nNew in Zulip 6.0 (feature level 142).\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanAdministerChannelGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to administer this channel.\n\nOrganization administrators can administer every channel as though they were\nin this group without being explicitly listed here.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: Prior to Zulip 10.0 (feature level 349) a user needed to\n[have content access](/help/channel-permissions) to a channel in\norder to modify it. The exception to this rule was that organization\nadministrators can edit channel names and descriptions without\nhaving full access to the channel.\n\nNew in Zulip 10.0 (feature level 325). Prior to this\nchange, the permission to administer channels was limited to realm\nadministrators.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanDeleteAnyMessageGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to delete any message in the channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete any message in the channel.\n\nUsers present in the organization-level `can_delete_any_message_group`\nsetting can always delete any message in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in `can_delete_any_message_group` were able\ndelete any message in the organization.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanDeleteOwnMessageGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to delete the messages that they have sent in the channel.\n\n[update-group-setting]: /api/group-setting-values#updating-group-setting-values\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to delete their own message in the channel.\n\nUsers with permission to delete any message in the channel\nand users present in the organization-level `can_delete_own_message_group` setting\ncan always delete their own messages in the channel if they\n[have content access](/help/channel-permissions) to that channel.\n\n**Changes**: New in Zulip 11.0 (feature level 407). Prior to this\nchange, only the users in the organization-level `can_delete_any_message_group`\nand `can_delete_own_message_group` settings were able delete their own messages in\nthe organization.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanMoveMessagesOutOfChannelGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to move messages out of this channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages out of the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_channels_group` setting can always move messages\nout of the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_channels_group` were able\nmove messages between channels.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanMoveMessagesWithinChannelGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to move messages within this channel.\n\nNote that a user must [have content access](/help/channel-permissions) to a\nchannel in order to move messages within the channel.\n\nChannel administrators and users present in the organization-level\n`can_move_messages_between_topics_group` setting can always move messages\nwithin the channel if they [have content access](/help/channel-permissions) to\nthe channel.\n\n**Changes**: New in Zulip 11.0 (feature level 396). Prior to this\nchange, only the users in `can_move_messages_between_topics_group` were able\nmove messages between topics of a channel.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanSendMessageGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to post in this channel.\n\nNote that a user must have metadata access to a channel and permission\nto administer the channel in order to modify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 333). Previously\n`stream_post_policy` field used to control the permission to\npost in the channel.\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanSubscribeGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to subscribe themselves to this channel.\n\nEveryone, excluding guests, can subscribe to any public channel\nirrespective of this setting.\n\nUsers in this group can subscribe to a private channel as well.\n\nNote that a user must [have content access](/help/channel-permissions)\nto a channel and permission to administer the channel in order to\nmodify this setting.\n\n**Changes**: New in Zulip 10.0 (feature level 357).\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "CanResolveTopicsGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/GroupSettingValue" - }, - { - "description": "A [group-setting value][setting-values] defining the set of users\nwho have permission to resolve topics in the channel.\n\nUsers who have similar realm-level permissions can resolve topics\nin a channel regardless of the value of this setting.\n\n**Changes**: New in Zulip 11.0 (feature level 402).\n\n[setting-values]: /api/group-setting-values\n" - } - ] - }, - "LinkifierPattern": { - "description": "The [Python regular\nexpression](https://docs.python.org/3/howto/regex.html) that should\ntrigger the linkifier.\n", - "type": "string", - "example": "#(?P[0-9]+)" - }, - "LinkifierURLTemplate": { - "description": "The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)\ncompliant URL template used for the link.\nIf you used named groups in `pattern`, you can insert their\ncontent here with `{name_of_group}`.\n\n**Changes**: New in Zulip 7.0 (feature level 176). This replaced\nthe `url_format_string` parameter, which was a format string in which\nnamed groups' content could be inserted with `%(name_of_group)s`.\n", - "type": "string", - "example": "https://github.com/zulip/zulip/issues/{id}" - }, - "FolderId": { - "type": "integer", - "nullable": true, - "description": "The ID of the folder to which the channel belongs.\n\nIs `null` if channel does not belong to any folder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" - } - }, - "responses": { - "SimpleSuccess": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/JsonSuccess" - } - } - } - }, - "SuccessIgnoredParameters": { - "description": "Success.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/IgnoredParametersSuccess" - } - ] - } - } - } - } - }, - "requestBodies": { - "UpdateUser": { - "required": false, - "content": { - "application/x-www-form-urlencoded": { - "schema": { - "type": "object", - "properties": { - "full_name": { - "description": "The user's full name.\n\n**Changes**: Removed unnecessary JSON-encoding of this parameter in\nZulip 5.0 (feature level 106).\n", - "type": "string", - "example": "NewName" - }, - "role": { - "description": "New [role](/api/roles-and-permissions) for the user. Roles are encoded as:\n\n- Organization owner: 100\n- Organization administrator: 200\n- Organization moderator: 300\n- Member: 400\n- Guest: 600\n\nOnly organization owners can add or remove the owner role.\n\nThe owner role cannot be removed from the only organization owner.\n\n**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous\npair of `is_admin` and `is_guest` boolean parameters. Organization moderator\nrole added in Zulip 4.0 (feature level 60).\n", - "type": "integer", - "example": 400 - }, - "profile_data": { - "description": "A dictionary containing the updated custom profile field data for the user.\n", - "type": "array", - "items": { - "type": "object" - }, - "example": [ - { - "id": 4, - "value": "0" - }, - { - "id": 5, - "value": "1909-04-05" - } - ] - }, - "new_email": { - "description": "New email address for the user. Requires the user making the request\nto be an organization owner and additionally have the `.can_change_user_emails`\nspecial permission.\n\n**Changes**: New in Zulip 10.0 (feature level 285).\n", - "type": "string", - "example": "username@example.com" - } - } - }, - "encoding": { - "role": { - "contentType": "application/json" - }, - "profile_data": { - "contentType": "application/json" - } - } - } - } - } - }, - "parameters": { - "UserGroupId": { - "name": "user_group_id", - "in": "path", - "description": "The ID of the target user group.\n", - "schema": { - "type": "integer" - }, - "example": 38, - "required": true - }, - "QueueId": { - "name": "queue_id", - "in": "query", - "description": "The ID of an event queue that was previously registered via\n`POST /api/v1/register` (see [Register a queue](/api/register-queue)).\n", - "schema": { - "type": "string" - }, - "example": "fb67bf8a-c031-47cc-84cf-ed80accacda8", - "required": true - }, - "ChannelIdInPath": { - "name": "stream_id", - "in": "path", - "description": "The ID of the channel to access.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - }, - "ClientGravatar": { - "name": "client_gravatar", - "in": "query", - "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n", - "schema": { - "type": "boolean", - "default": true - }, - "example": false - }, - "MessageId": { - "name": "message_id", - "in": "path", - "description": "The target message's ID.\n", - "schema": { - "type": "integer" - }, - "example": 43, - "required": true - }, - "UserId": { - "name": "user_id", - "in": "path", - "description": "The target user's ID.\n", - "schema": { - "type": "integer" - }, - "example": 12, - "required": true - }, - "MutedUserId": { - "name": "muted_user_id", - "in": "path", - "description": "The ID of the user to mute/unmute.\n\n**Changes**: Before Zulip 8.0 (feature level 188), bot users could not\nbe muted/unmuted, and specifying a bot user's ID returned an error response.\n", - "schema": { - "type": "integer" - }, - "example": 10, - "required": true - }, - "IncludeSubscribers": { - "name": "include_subscribers", - "in": "query", - "description": "Whether each returned channel object should include a `subscribers`\nfield containing a list of the user IDs of its subscribers.\n\nClient apps supporting organizations with many thousands of users\nshould not pass `true`, because the full subscriber matrix may be\nseveral megabytes of data. The `partial` value, combined with the\n`subscriber_count` and fetching subscribers for individual channels as\nneeded, is recommended to support client app features where\nchannel subscriber data is useful.\n\nIf a client passes `partial` for this parameter, the server may,\nfor some channels, return a subset of the channel's subscribers\nin the `partial_subscribers` field instead of the `subscribers` field,\nwhich always contains the complete set of subscribers.\n\nThe server guarantees that it will always return a `subscribers`\nfield for channels with fewer than 250 total subscribers. When\nreturning a `partial_subscribers` field, the server guarantees\nthat all bot users and users active within the last 14 days will\nbe included. For other cases, the server may use its discretion\nto determine which channels and users to include, balancing between\npayload size and usefulness of the data provided to the client.\n\n**Changes**: The `partial` value is new in Zulip 11.0 (feature level 412).\n\nNew in Zulip 2.1.0.\n", - "schema": { - "type": "string", - "enum": ["true", "false", "partial"], - "default": "false" - }, - "example": "true" - }, - "IncludeCustomProfileFields": { - "name": "include_custom_profile_fields", - "in": "query", - "description": "Whether the client wants [custom profile field](/help/custom-profile-fields)\ndata to be included in the response.\n\n**Changes**: New in Zulip 2.1.0. Previous versions do not offer these\ndata via the API.\n", - "schema": { - "type": "boolean", - "default": false - }, - "example": true - }, - "DirectMemberOnly": { - "name": "direct_member_only", - "in": "query", - "description": "Whether to consider only the direct members of user group and not members\nof its subgroups. Default is `false`.\n", - "schema": { - "type": "boolean" - }, - "example": false, - "required": false - }, - "ChannelFolderId": { - "name": "channel_folder_id", - "in": "path", - "description": "The ID of the target channel folder.\n", - "schema": { - "type": "integer" - }, - "example": 1, - "required": true - } - } - } -} diff --git a/forms-bridge/addons/zulip/templates/contact.php b/forms-bridge/addons/zulip/templates/contact.php index 0cd89563..101ee6c6 100644 --- a/forms-bridge/addons/zulip/templates/contact.php +++ b/forms-bridge/addons/zulip/templates/contact.php @@ -10,7 +10,7 @@ } return array( - 'title' => __( 'Contacts', 'forms-bridge' ), + 'title' => __( 'Contacts Stream', 'forms-bridge' ), 'description' => __( 'Contact form template. The resulting bridge will notify form submissions in a Zulip stream', 'forms-bridge' @@ -44,7 +44,7 @@ 'label' => __( 'Topic', 'forms-bridge' ), 'description' => __( 'Topic under which the messages will be notified', 'forms-bridge' ), 'type' => 'text', - 'default' => 'WordPress', + 'default' => 'WordPress Contacts', 'required' => true, ), array(